cpython-lru_cache-weakref: Doc/tut.tex annotate

annotate Doc/tut.tex @ 5817:48b94de85bf3 legacy-trunk

Extensive changes by AMK.

author	Guido van Rossum <guido@python.org>
date	Thu, 17 Jul 1997 16:29:42 +0000
parents	d320ca843512
children	630725805c66

rev	line source
808 0cff36b110fe Moved a4wide option to myformat.sty Guido van Rossum <guido@python.org> parents: 797 diff changeset	1 \documentstyle[twoside,11pt,myformat]{report}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3 % Things to do:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	4 % Add a section on file I/O
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	5 % Write a chapter entitled ``Some Useful Modules''
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	6 % --regex, math+cmath
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	7 % Should really move the Python startup file info to an appendix
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	8 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	9
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	10 \title{Python Tutorial -- DRAFT of \today}
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	11
f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	12 \input{boilerplate}
1412 00f1e8864dcc * {lib,ref,ext,tut}.tex: added explicit \date{<date> \\ <release>}. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	13
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	14 \begin{document}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	15
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	16 \pagenumbering{roman}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	17
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	18 \maketitle
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	19
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	20 \input{copyright}
f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	21
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	22 \begin{abstract}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	23
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	24 \noindent
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	25 Python is a simple, yet powerful programming language that bridges the
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	26 gap between C and shell programming, and is thus ideally suited for
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	27 ``throw-away programming'' and rapid prototyping. Its syntax is put
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	28 together from constructs borrowed from a variety of other languages;
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	29 most prominent are influences from ABC, C, Modula-3 and Icon.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	30
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	31 The Python interpreter is easily extended with new functions and data
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	32 types implemented in C. Python is also suitable as an extension
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	33 language for highly customizable C applications such as editors or
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	34 window managers.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	35
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	36 Python is available for many operating systems:
4727 9ac9ea848d7d (tut.tex): Normalized all uses of "UNIX" and "{\UNIX}" to use "\UNIX{}", Fred Drake <fdrake@acm.org> parents: 4513 diff changeset	37 several flavors of \UNIX{}, the Apple Macintosh, MS-DOS, Windows
4491 6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	38 (3.1(1), '95 and NT flavors), OS/2, and others.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	39
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	40 This tutorial introduces the reader informally to the basic concepts
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	41 and features of the Python language and system. It helps to have a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	42 Python interpreter handy for hands-on experience, but as the examples
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	43 are self-contained, the tutorial can be read off-line as well.
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	44
452 ae1a555e65fa The Reference Manual is now official. Guido van Rossum <guido@python.org> parents: 440 diff changeset	45 For a description of standard objects and modules, see the {\em Python
ae1a555e65fa The Reference Manual is now official. Guido van Rossum <guido@python.org> parents: 440 diff changeset	46 Library Reference} document. The {\em Python Reference Manual} gives
ae1a555e65fa The Reference Manual is now official. Guido van Rossum <guido@python.org> parents: 440 diff changeset	47 a more formal definition of the language.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	48
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	49 \end{abstract}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	50
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	51 \pagebreak
670 2cddbbea9bfb Set parskip to 0 in the table of content. Guido van Rossum <guido@python.org> parents: 563 diff changeset	52 {
2cddbbea9bfb Set parskip to 0 in the table of content. Guido van Rossum <guido@python.org> parents: 563 diff changeset	53 \parskip = 0mm
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	54 \tableofcontents
670 2cddbbea9bfb Set parskip to 0 in the table of content. Guido van Rossum <guido@python.org> parents: 563 diff changeset	55 }
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	56
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	57 \pagebreak
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	58
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	59 \pagenumbering{arabic}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	60
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	61
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	62 \chapter{Whetting Your Appetite}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	63
4491 6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	64 \section{Disclaimer}
6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	65
6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	66 Now that there are several books out on Python, this tutorial has lost
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	67 its role as the only introduction to Python for most new users. This
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	68 tutorial does not attempt to be comprehensive and cover every single
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	69 feature, or even every commonly used feature. Instead, it introduces
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	70 many of Python's most noteworthy features, and will give you a good
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	71 idea of the language's flavor and style.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	72
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	73 %It takes time to keep a document like this up to date in the face of
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	74 %additions to the language, and I simply don't have enough time to do a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	75 %good job. Therefore, this version of the tutorial is almost unchanged
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	76 %since the previous release. This doesn't mean that the tutorial is
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	77 %out of date --- all the examples still work exactly as before. There
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	78 %are simply some new areas of the language that aren't covered.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	79
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	80 %To make up for this, there are some chapters at the end that cover
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	81 %important changes in recent Python releases, and these are up to date
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	82 %with the current release.
4491 6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	83
6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	84 \section{Introduction}
6a75b3cf023c Done with the "New in 1.4" chapter. Guido van Rossum <guido@python.org> parents: 4452 diff changeset	85
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	86 If you ever wrote a large shell script, you probably know this
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	87 feeling: you'd love to add yet another feature, but it's already so
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	88 slow, and so big, and so complicated; or the feature involves a system
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	89 call or other function that is only accessible from C \ldots Usually
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	90 the problem at hand isn't serious enough to warrant rewriting the
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	91 script in C; perhaps the problem requires variable-length strings or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	92 other data types (like sorted lists of file names) that are easy in
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	93 the shell but lots of work to implement in C, or perhaps you're not
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	94 sufficiently familiar with C.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	95
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	96 Another situation: perhaps you have to work with several C libraries,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	97 and the usual C write/compile/test/re-compile cycle is too slow. You
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	98 need to develop software more quickly. Possibly perhaps you've
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	99 written a program that could use an extension language, and you don't
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	100 want to design a language, write and debug an interpreter for it, then
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	101 tie it into your application.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	102
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	103 In such cases, Python may be just the language for you. Python is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	104 simple to use, but it is a real programming language, offering much
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	105 more structure and support for large programs than the shell has. On
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	106 the other hand, it also offers much more error checking than C, and,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	107 being a {\em very-high-level language}, it has high-level data types
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	108 built in, such as flexible arrays and dictionaries that would cost you
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	109 days to implement efficiently in C. Because of its more general data
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	110 types Python is applicable to a much larger problem domain than {\em
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	111 Awk} or even {\em Perl}, yet many things are at least as easy in
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	112 Python as in those languages.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	113
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	114 Python allows you to split up your program in modules that can be
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	115 reused in other Python programs. It comes with a large collection of
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	116 standard modules that you can use as the basis of your programs --- or
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	117 as examples to start learning to program in Python. There are also
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	118 built-in modules that provide things like file I/O, system calls,
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	119 sockets, and even interfaces to GUI toolkits like Tk.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	120
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	121 Python is an interpreted language, which can save you considerable time
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	122 during program development because no compilation and linking is
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	123 necessary. The interpreter can be used interactively, which makes it
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	124 easy to experiment with features of the language, to write throw-away
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	125 programs, or to test functions during bottom-up program development.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	126 It is also a handy desk calculator.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	127
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	128 Python allows writing very compact and readable programs. Programs
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	129 written in Python are typically much shorter than equivalent C
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	130 programs, for several reasons:
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	131 \begin{itemize}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	132 \item
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	133 the high-level data types allow you to express complex operations in a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	134 single statement;
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	135 \item
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	136 statement grouping is done by indentation instead of begin/end
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	137 brackets;
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	138 \item
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	139 no variable or argument declarations are necessary.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	140 \end{itemize}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	141
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	142 Python is {\em extensible}: if you know how to program in C it is easy
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	143 to add a new built-in function or module to the interpreter, either to
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	144 perform critical operations at maximum speed, or to link Python
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	145 programs to libraries that may only be available in binary form (such
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	146 as a vendor-specific graphics library). Once you are really hooked,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	147 you can link the Python interpreter into an application written in C
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	148 and use it as an extension or command language for that application.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	149
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	150 By the way, the language is named after the BBC show ``Monty Python's
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	151 Flying Circus'' and has nothing to do with nasty reptiles. Making
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	152 references to Monty Python skits in documentation is not only allowed,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	153 it is encouraged.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	154
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	155 \section{Where From Here}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	156
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	157 Now that you are all excited about Python, you'll want to examine it
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	158 in some more detail. Since the best way to learn a language is
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	159 using it, you are invited here to do so.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	160
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	161 In the next chapter, the mechanics of using the interpreter are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	162 explained. This is rather mundane information, but essential for
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	163 trying out the examples shown later.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	164
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	165 The rest of the tutorial introduces various features of the Python
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	166 language and system though examples, beginning with simple
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	167 expressions, statements and data types, through functions and modules,
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	168 and finally touching upon advanced concepts like exceptions
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	169 and user-defined classes.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	170
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	171 \chapter{Using the Python Interpreter}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	172
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	173 \section{Invoking the Interpreter}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	174
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	175 The Python interpreter is usually installed as {\tt /usr/local/bin/python}
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	176 on those machines where it is available; putting {\tt /usr/local/bin} in
4727 9ac9ea848d7d (tut.tex): Normalized all uses of "UNIX" and "{\UNIX}" to use "\UNIX{}", Fred Drake <fdrake@acm.org> parents: 4513 diff changeset	177 your \UNIX{} shell's search path makes it possible to start it by
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	178 typing the command
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	179
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	180 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	181 python
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	182 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	183 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	184 to the shell. Since the choice of the directory where the interpreter
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	185 lives is an installation option, other places are possible; check with
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	186 your local Python guru or system administrator. (E.g., {\tt
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	187 /usr/local/python} is a popular alternative location.)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	188
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	189 Typing an EOF character (Control-D on \UNIX{}, Control-Z or F6 on DOS
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	190 or Windows) at the primary prompt causes the interpreter to exit with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	191 a zero exit status. If that doesn't work, you can exit the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	192 interpreter by typing the following commands: \code{import sys ;
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	193 sys.exit()}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	194
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	195 The interpreter's line-editing features usually aren't very
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	196 sophisticated. On Unix, whoever installed the interpreter may have
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	197 enabled support for the GNU readline library, which adds more
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	198 elaborate interactive editing and history features. Perhaps the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	199 quickest check to see whether command line editing is supported is
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	200 typing Control-P to the first Python prompt you get. If it beeps, you
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	201 have command line editing; see Appendix A for an introduction to the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	202 keys. If nothing appears to happen, or if \verb/^P/ is echoed,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	203 command line editing isn't available; you'll only be able to use
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	204 backspace to remove characters from the current line.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	205
4727 9ac9ea848d7d (tut.tex): Normalized all uses of "UNIX" and "{\UNIX}" to use "\UNIX{}", Fred Drake <fdrake@acm.org> parents: 4513 diff changeset	206 The interpreter operates somewhat like the \UNIX{} shell: when called
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	207 with standard input connected to a tty device, it reads and executes
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	208 commands interactively; when called with a file name argument or with
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	209 a file as standard input, it reads and executes a {\em script} from
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	210 that file.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	211
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	212 A third way of starting the interpreter is
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	213 ``{\tt python -c command [arg] ...}'', which
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	214 executes the statement(s) in {\tt command}, analogous to the shell's
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	215 {\tt -c} option. Since Python statements often contain spaces or other
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	216 characters that are special to the shell, it is best to quote {\tt
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	217 command} in its entirety with double quotes.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	218
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	219 Note that there is a difference between ``{\tt python file}'' and
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	220 ``{\tt python <file}''. In the latter case, input requests from the
697 7c06bf15fd2a _ can now be a normal character. Guido van Rossum <guido@python.org> parents: 670 diff changeset	221 program, such as calls to {\tt input()} and {\tt raw_input()}, are
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	222 satisfied from {\em file}. Since this file has already been read
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	223 until the end by the parser before the program starts executing, the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	224 program will encounter EOF immediately. In the former case (which is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	225 usually what you want) they are satisfied from whatever file or device
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	226 is connected to standard input of the Python interpreter.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	227
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	228 When a script file is used, it is sometimes useful to be able to run
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	229 the script and enter interactive mode afterwards. This can be done by
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	230 passing {\tt -i} before the script. (This does not work if the script
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	231 is read from standard input, for the same reason as explained in the
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	232 previous paragraph.)
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	233
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	234 \subsection{Argument Passing}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	235
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	236 When known to the interpreter, the script name and additional
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	237 arguments thereafter are passed to the script in the variable {\tt
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	238 sys.argv}, which is a list of strings. Its length is at least one;
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	239 when no script and no arguments are given, {\tt sys.argv[0]} is an
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	240 empty string. When the script name is given as {\tt '-'} (meaning
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	241 standard input), {\tt sys.argv[0]} is set to {\tt '-'}. When {\tt -c
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	242 command} is used, {\tt sys.argv[0]} is set to {\tt '-c'}. Options
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	243 found after {\tt -c command} are not consumed by the Python
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	244 interpreter's option processing but left in {\tt sys.argv} for the
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	245 command to handle.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	246
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	247 \subsection{Interactive Mode}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	248
283 ed0162558929 Mention "-c command" option. Guido van Rossum <guido@python.org> parents: 271 diff changeset	249 When commands are read from a tty, the interpreter is said to be in
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	250 {\em interactive\ mode}. In this mode it prompts for the next command
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	251 with the {\em primary\ prompt}, usually three greater-than signs ({\tt
3081 eada248676de move uncomfortable backslash Guido van Rossum <guido@python.org> parents: 2942 diff changeset	252 >>>}); for continuation lines it prompts with the
eada248676de move uncomfortable backslash Guido van Rossum <guido@python.org> parents: 2942 diff changeset	253 {\em secondary\ prompt},
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	254 by default three dots ({\tt ...}).
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	255
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	256 The interpreter prints a welcome message stating its version number
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	257 and a copyright notice before printing the first prompt, e.g.:
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	258
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	259 \bcode\begin{verbatim}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	260 python
4452 edab097882d8 Got rid of most XXXes in the News chapter. Bumped the version to 1.4. Guido van Rossum <guido@python.org> parents: 4379 diff changeset	261 Python 1.4 (Oct 25 1996) [GCC 2.7.2]
4118 a86407b3c3ac Version number; started chapter on what's new in 1.4 Guido van Rossum <guido@python.org> parents: 3659 diff changeset	262 Copyright 1991-1996 Stichting Mathematisch Centrum, Amsterdam
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	263 >>>
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	264 \end{verbatim}\ecode
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	265
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	266 \section{The Interpreter and its Environment}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	267
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	268 \subsection{Error Handling}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	269
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	270 When an error occurs, the interpreter prints an error
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	271 message and a stack trace. In interactive mode, it then returns to
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	272 the primary prompt; when input came from a file, it exits with a
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	273 nonzero exit status after printing
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	274 the stack trace. (Exceptions handled by an {\tt except} clause in a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	275 {\tt try} statement are not errors in this context.) Some errors are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	276 unconditionally fatal and cause an exit with a nonzero exit; this
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	277 applies to internal inconsistencies and some cases of running out of
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	278 memory. All error messages are written to the standard error stream;
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	279 normal output from the executed commands is written to standard
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	280 output.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	281
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	282 Typing the interrupt character (usually Control-C or DEL) to the
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	283 primary or secondary prompt cancels the input and returns to the
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	284 primary prompt.%
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	285 \footnote{
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	286 A problem with the GNU Readline package may prevent this.
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	287 }
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	288 Typing an interrupt while a command is executing raises the {\tt
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	289 KeyboardInterrupt} exception, which may be handled by a {\tt try}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	290 statement.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	291
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	292 \subsection{Executable Python scripts}
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	293
4727 9ac9ea848d7d (tut.tex): Normalized all uses of "UNIX" and "{\UNIX}" to use "\UNIX{}", Fred Drake <fdrake@acm.org> parents: 4513 diff changeset	294 On BSD'ish \UNIX{} systems, Python scripts can be made directly
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	295 executable, like shell scripts, by putting the line
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	296
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	297 \bcode\begin{verbatim}
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	298 #! /usr/local/bin/python
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	299 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	300 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	301 (assuming that's the name of the interpreter) at the beginning of the
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	302 script and giving the file an executable mode. The {\tt \#!} must be
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	303 the first two characters of the file.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	304
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	305 \subsection{The Interactive Startup File}
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	306
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	307 XXX This should probably be dumped in an appendix, since most people
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	308 don't use Python interactively in non-trivial ways.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	309
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	310 When you use Python interactively, it is frequently handy to have some
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	311 standard commands executed every time the interpreter is started. You
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	312 can do this by setting an environment variable named {\tt
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	313 PYTHONSTARTUP} to the name of a file containing your start-up
4727 9ac9ea848d7d (tut.tex): Normalized all uses of "UNIX" and "{\UNIX}" to use "\UNIX{}", Fred Drake <fdrake@acm.org> parents: 4513 diff changeset	314 commands. This is similar to the {\tt .profile} feature of the \UNIX{}
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	315 shells.
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	316
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	317 This file is only read in interactive sessions, not when Python reads
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	318 commands from a script, and not when {\tt /dev/tty} is given as the
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	319 explicit source of commands (which otherwise behaves like an
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	320 interactive session). It is executed in the same name space where
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	321 interactive commands are executed, so that objects that it defines or
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	322 imports can be used without qualification in the interactive session.
1040 0ee59a14e542 Added hint about changing the prompt in $PYTHONSTARTUP Guido van Rossum <guido@python.org> parents: 1030 diff changeset	323 You can also change the prompts {\tt sys.ps1} and {\tt sys.ps2} in
0ee59a14e542 Added hint about changing the prompt in $PYTHONSTARTUP Guido van Rossum <guido@python.org> parents: 1030 diff changeset	324 this file.
1030 9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	325
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	326 If you want to read an additional start-up file from the current
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	327 directory, you can program this in the global start-up file, e.g.
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	328 \verb\execfile('.pythonrc')\. If you want to use the startup file
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	329 in a script, you must write this explicitly in the script, e.g.
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	330 \verb\import os;\ \verb\execfile(os.environ['PYTHONSTARTUP'])\.
9f0fb114c1e5 Changed references to /usr/local into /usr/local/bin. Guido van Rossum <guido@python.org> parents: 952 diff changeset	331
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	332 \chapter{An Informal Introduction to Python}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	333
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	334 In the following examples, input and output are distinguished by the
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	335 presence or absence of prompts ({\tt >>>} and {\tt ...}): to repeat
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	336 the example, you must type everything after the prompt, when the
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	337 prompt appears; lines that do not begin with a prompt are output from
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	338 the interpreter.%
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	339 %\footnote{
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	340 % I'd prefer to use different fonts to distinguish input
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	341 % from output, but the amount of LaTeX hacking that would require
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	342 % is currently beyond my ability.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	343 %}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	344 Note that a secondary prompt on a line by itself in an example means
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	345 you must type a blank line; this is used to end a multi-line command.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	346
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	347 \section{Using Python as a Calculator}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	348
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	349 Let's try some simple Python commands. Start the interpreter and wait
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	350 for the primary prompt, {\tt >>>}. (It shouldn't take long.)
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	351
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	352 \subsection{Numbers}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	353
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	354 The interpreter acts as a simple calculator: you can type an
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	355 expression at it and it will write the value. Expression syntax is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	356 straightforward: the operators {\tt +}, {\tt -}, {\tt *} and {\tt /}
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	357 work just like in most other languages (e.g., Pascal or C); parentheses
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	358 can be used for grouping. For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	359
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	360 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	361 >>> 2+2
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	362 4
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	363 >>> # This is a comment
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	364 ... 2+2
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	365 4
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	366 >>> 2+2 # and a comment on the same line as code
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	367 4
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	368 >>> (50-5*6)/4
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	369 5
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	370 >>> # Integer division returns the floor:
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	371 ... 7/3
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	372 2
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	373 >>> 7/-3
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	374 -3
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	375 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	376 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	377 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	378 Like in C, the equal sign ({\tt =}) is used to assign a value to a
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	379 variable. The value of an assignment is not written:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	380
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	381 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	382 >>> width = 20
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	383 >>> height = 5*9
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	384 >>> width * height
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	385 900
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	386 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	387 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	388 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	389 A value can be assigned to several variables simultaneously:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	390
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	391 \bcode\begin{verbatim}
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	392 >>> x = y = z = 0 # Zero x, y and z
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	393 >>> x
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	394 0
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	395 >>> y
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	396 0
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	397 >>> z
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	398 0
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	399 >>>
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	400 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	401 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	402 There is full support for floating point; operators with mixed type
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	403 operands convert the integer operand to floating point:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	404
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	405 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	406 >>> 4 * 2.5 / 3.3
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	407 3.0303030303
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	408 >>> 7.0 / 2
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	409 3.5
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	410 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	411 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	412 Complex numbers are also supported; imaginary numbers are written with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	413 a suffix of \code{'j'} or \code{'J'}. Complex numbers with a nonzero
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	414 real component are written as \code{(\var{real}+\var{imag}j)}, or can
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	415 be created with the \code{complex(\var{real}, \var{imag})} function.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	416
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	417 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	418 >>> 1j * 1J
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	419 (-1+0j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	420 >>> 1j * complex(0,1)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	421 (-1+0j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	422 >>> 3+1j*3
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	423 (3+3j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	424 >>> (3+1j)*3
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	425 (9+3j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	426 >>> (1+2j)/(1+1j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	427 (1.5+0.5j)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	428 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	429 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	430 Complex numbers are always represented as two floating point numbers,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	431 the real and imaginary part. To extract these parts from a complex
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	432 number \code{z}, use \code{z.real} and \code{z.imag}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	433
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	434 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	435 >>> a=1.5+0.5j
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	436 >>> a.real
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	437 1.5
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	438 >>> a.imag
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	439 0.5
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	440 \end{verbatim}\ecode
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	441 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	442 The conversion functions to floating point and integer
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	443 (\code{float()}, \code{int()} and \code{long()}) don't work for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	444 complex numbers --- there is no one correct way to convert a complex
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	445 number to a real number. Use \code{abs(z)} to get its magnitude (as a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	446 float) or \code{z.real} to get its real part.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	447
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	448 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	449 >>> a=1.5+0.5j
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	450 >>> float(a)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	451 Traceback (innermost last):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	452 File "<stdin>", line 1, in ?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	453 TypeError: can't convert complex to float; use e.g. abs(z)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	454 >>> a.real
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	455 1.5
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	456 >>> abs(a)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	457 1.58113883008
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	458 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	459 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	460 In interactive mode, the last printed expression is assigned to the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	461 variable \code{_}. This means that when you are using Python as a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	462 desk calculator, it is somewhat easier to continue calculations, for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	463 example:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	464
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	465 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	466 >>> tax = 17.5 / 100
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	467 >>> price = 3.50
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	468 >>> price * tax
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	469 0.6125
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	470 >>> price + _
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	471 4.1125
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	472 >>> round(_, 2)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	473 4.11
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	474 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	475
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	476 This variable should be treated as read-only by the user. Don't
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	477 explicitly assign a value to it --- you would create an independent
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	478 local variable with the same name masking the built-in variable with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	479 its magic behavior.
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	480
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	481 \subsection{Strings}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	482
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	483 Besides numbers, Python can also manipulate strings, which can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	484 expressed in several ways. They can be enclosed in single quotes or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	485 double quotes:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	486
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	487 \bcode\begin{verbatim}
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	488 >>> 'spam eggs'
5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	489 'spam eggs'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	490 >>> 'doesn\'t'
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	491 "doesn't"
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	492 >>> "doesn't"
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	493 "doesn't"
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	494 >>> '"Yes," he said.'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	495 '"Yes," he said.'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	496 >>> "\"Yes,\" he said."
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	497 '"Yes," he said.'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	498 >>> '"Isn\'t," she said.'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	499 '"Isn\'t," she said.'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	500 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	501 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	502 %
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	503 String literals can span multiple lines in several ways. Newlines can be escaped with backslashes, e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	504
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	505 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	506 hello = "This is a rather long string containing\n\
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	507 several lines of text just as you would do in C.\n\
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	508 Note that whitespace at the beginning of the line is\
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	509 significant.\n"
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	510 print hello
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	511 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	512
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	513 which would print the following:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	514 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	515 This is a rather long string containing
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	516 several lines of text just as you would do in C.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	517 Note that whitespace at the beginning of the line is significant.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	518 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	519
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	520 Or, strings can be surrounded in a pair of matching triple-quotes:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	521 \code{"""} or \code {'''}. End of lines do not need to be escaped
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	522 when using triple-quotes, but they will be included in the string.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	523
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	524 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	525 print """
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	526 Usage: thingy [OPTIONS]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	527 -h Display this usage message
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	528 -H hostname Hostname to connect to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	529 """
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	530 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	531
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	532 produces the following output:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	533
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	534 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	535 Usage: thingy [OPTIONS]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	536 -h Display this usage message
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	537 -H hostname Hostname to connect to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	538 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	539 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	540 The interpreter prints the result of string operations in the same way
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	541 as they are typed for input: inside quotes, and with quotes and other
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	542 funny characters escaped by backslashes, to show the precise
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	543 value. The string is enclosed in double quotes if the string contains
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	544 a single quote and no double quotes, else it's enclosed in single
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	545 quotes. (The {\tt print} statement, described later, can be used to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	546 write strings without quotes or escapes.)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	547
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	548 Strings can be concatenated (glued together) with the {\tt +}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	549 operator, and repeated with {\tt *}:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	550
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	551 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	552 >>> word = 'Help' + 'A'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	553 >>> word
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	554 'HelpA'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	555 >>> '<' + word*5 + '>'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	556 '<HelpAHelpAHelpAHelpAHelpA>'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	557 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	558 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	559 %
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	560 Two string literals next to each other are automatically concatenated;
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	561 the first line above could also have been written \code{word = 'Help'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	562 'A'}; this only works with two literals, not with arbitrary string expressions.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	563
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	564 Strings can be subscripted (indexed); like in C, the first character
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	565 of a string has subscript (index) 0. There is no separate character
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	566 type; a character is simply a string of size one. Like in Icon,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	567 substrings can be specified with the {\em slice} notation: two indices
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	568 separated by a colon.
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	569
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	570 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	571 >>> word[4]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	572 'A'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	573 >>> word[0:2]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	574 'He'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	575 >>> word[2:4]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	576 'lp'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	577 >>>
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	578 \end{verbatim}\ecode
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	579 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	580 Slice indices have useful defaults; an omitted first index defaults to
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	581 zero, an omitted second index defaults to the size of the string being
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	582 sliced.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	583
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	584 \bcode\begin{verbatim}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	585 >>> word[:2] # The first two characters
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	586 'He'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	587 >>> word[2:] # All but the first two characters
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	588 'lpA'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	589 >>>
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	590 \end{verbatim}\ecode
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	591 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	592 Here's a useful invariant of slice operations: \verb\s[:i] + s[i:]\
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	593 equals \verb\s\.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	594
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	595 \bcode\begin{verbatim}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	596 >>> word[:2] + word[2:]
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	597 'HelpA'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	598 >>> word[:3] + word[3:]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	599 'HelpA'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	600 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	601 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	602 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	603 Degenerate slice indices are handled gracefully: an index that is too
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	604 large is replaced by the string size, an upper bound smaller than the
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	605 lower bound returns an empty string.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	606
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	607 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	608 >>> word[1:100]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	609 'elpA'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	610 >>> word[10:]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	611 ''
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	612 >>> word[2:1]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	613 ''
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	614 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	615 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	616 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	617 Indices may be negative numbers, to start counting from the right.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	618 For example:
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	619
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	620 \bcode\begin{verbatim}
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	621 >>> word[-1] # The last character
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	622 'A'
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	623 >>> word[-2] # The last-but-one character
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	624 'p'
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	625 >>> word[-2:] # The last two characters
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	626 'pA'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	627 >>> word[:-2] # All but the last two characters
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	628 'Hel'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	629 >>>
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	630 \end{verbatim}\ecode
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	631 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	632 But note that -0 is really the same as 0, so it does not count from
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	633 the right!
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	634
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	635 \bcode\begin{verbatim}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	636 >>> word[-0] # (since -0 equals 0)
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	637 'H'
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	638 >>>
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	639 \end{verbatim}\ecode
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	640 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	641 Out-of-range negative slice indices are truncated, but don't try this
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	642 for single-element (non-slice) indices:
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	643
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	644 \bcode\begin{verbatim}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	645 >>> word[-100:]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	646 'HelpA'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	647 >>> word[-10] # error
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	648 Traceback (innermost last):
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	649 File "<stdin>", line 1
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	650 IndexError: string index out of range
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	651 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	652 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	653 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	654 The best way to remember how slices work is to think of the indices as
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	655 pointing {\em between} characters, with the left edge of the first
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	656 character numbered 0. Then the right edge of the last character of a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	657 string of {\tt n} characters has index {\tt n}, for example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	658
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	659 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	660 +---+---+---+---+---+
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	661 \| H \| e \| l \| p \| A \|
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	662 +---+---+---+---+---+
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	663 0 1 2 3 4 5
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	664 -5 -4 -3 -2 -1
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	665 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	666 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	667 The first row of numbers gives the position of the indices 0...5 in
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	668 the string; the second row gives the corresponding negative indices.
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	669 The slice from \verb\i\ to \verb\j\ consists of all characters between
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	670 the edges labeled \verb\i\ and \verb\j\, respectively.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	671
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	672 For nonnegative indices, the length of a slice is the difference of
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	673 the indices, if both are within bounds, e.g., the length of
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	674 \verb\word[1:3]\ is 2.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	675
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	676 The built-in function {\tt len()} returns the length of a string:
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	677
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	678 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	679 >>> s = 'supercalifragilisticexpialidocious'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	680 >>> len(s)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	681 34
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	682 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	683 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	684
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	685 \subsection{Lists}
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	686
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	687 Python knows a number of {\em compound} data types, used to group
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	688 together other values. The most versatile is the {\em list}, which
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	689 can be written as a list of comma-separated values (items) between
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	690 square brackets. List items need not all have the same type.
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	691
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	692 \bcode\begin{verbatim}
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	693 >>> a = ['spam', 'eggs', 100, 1234]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	694 >>> a
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	695 ['spam', 'eggs', 100, 1234]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	696 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	697 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	698 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	699 Like string indices, list indices start at 0, and lists can be sliced,
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	700 concatenated and so on:
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	701
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	702 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	703 >>> a[0]
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	704 'spam'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	705 >>> a[3]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	706 1234
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	707 >>> a[-2]
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	708 100
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	709 >>> a[1:-1]
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	710 ['eggs', 100]
5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	711 >>> a[:2] + ['bacon', 2*2]
5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	712 ['spam', 'eggs', 'bacon', 4]
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	713 >>> 3*a[:3] + ['Boe!']
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	714 ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	715 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	716 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	717 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	718 Unlike strings, which are {\em immutable}, it is possible to change
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	719 individual elements of a list:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	720
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	721 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	722 >>> a
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	723 ['spam', 'eggs', 100, 1234]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	724 >>> a[2] = a[2] + 23
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	725 >>> a
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	726 ['spam', 'eggs', 123, 1234]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	727 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	728 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	729 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	730 Assignment to slices is also possible, and this can even change the size
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	731 of the list:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	732
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	733 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	734 >>> # Replace some items:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	735 ... a[0:2] = [1, 12]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	736 >>> a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	737 [1, 12, 123, 1234]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	738 >>> # Remove some:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	739 ... a[0:2] = []
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	740 >>> a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	741 [123, 1234]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	742 >>> # Insert some:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	743 ... a[1:1] = ['bletch', 'xyzzy']
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	744 >>> a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	745 [123, 'bletch', 'xyzzy', 1234]
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	746 >>> a[:0] = a # Insert (a copy of) itself at the beginning
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	747 >>> a
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	748 [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	749 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	750 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	751 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	752 The built-in function {\tt len()} also applies to lists:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	753
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	754 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	755 >>> len(a)
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	756 8
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	757 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	758 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	759 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	760 It is possible to nest lists (create lists containing other lists),
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	761 for example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	762
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	763 \bcode\begin{verbatim}
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	764 >>> q = [2, 3]
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	765 >>> p = [1, q, 4]
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	766 >>> len(p)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	767 3
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	768 >>> p[1]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	769 [2, 3]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	770 >>> p[1][0]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	771 2
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	772 >>> p[1].append('xtra') # See section 5.1
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	773 >>> p
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	774 [1, [2, 3, 'xtra'], 4]
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	775 >>> q
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	776 [2, 3, 'xtra']
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	777 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	778 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	779 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	780 Note that in the last example, {\tt p[1]} and {\tt q} really refer to
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	781 the same object! We'll come back to {\em object semantics} later.
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	782
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	783 \section{First Steps Towards Programming}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	784
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	785 Of course, we can use Python for more complicated tasks than adding
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	786 two and two together. For instance, we can write an initial
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	787 subsequence of the {\em Fibonacci} series as follows:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	788
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	789 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	790 >>> # Fibonacci series:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	791 ... # the sum of two elements defines the next
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	792 ... a, b = 0, 1
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	793 >>> while b < 10:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	794 ... print b
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	795 ... a, b = b, a+b
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	796 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	797 1
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	798 1
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	799 2
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	800 3
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	801 5
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	802 8
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	803 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	804 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	805 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	806 This example introduces several new features.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	807
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	808 \begin{itemize}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	809
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	810 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	811 The first line contains a {\em multiple assignment}: the variables
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	812 {\tt a} and {\tt b} simultaneously get the new values 0 and 1. On the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	813 last line this is used again, demonstrating that the expressions on
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	814 the right-hand side are all evaluated first before any of the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	815 assignments take place.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	816
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	817 \item
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	818 The {\tt while} loop executes as long as the condition (here: {\tt b <
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	819 10}) remains true. In Python, like in C, any non-zero integer value is
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	820 true; zero is false. The condition may also be a string or list value,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	821 in fact any sequence; anything with a non-zero length is true, empty
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	822 sequences are false. The test used in the example is a simple
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	823 comparison. The standard comparison operators are written the same as
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	824 in C: {\tt <}, {\tt >}, {\tt ==}, {\tt <=}, {\tt >=} and {\tt !=}.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	825
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	826 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	827 The {\em body} of the loop is {\em indented}: indentation is Python's
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	828 way of grouping statements. Python does not (yet!) provide an
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	829 intelligent input line editing facility, so you have to type a tab or
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	830 space(s) for each indented line. In practice you will prepare more
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	831 complicated input for Python with a text editor; most text editors have
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	832 an auto-indent facility. When a compound statement is entered
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	833 interactively, it must be followed by a blank line to indicate
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	834 completion (since the parser cannot guess when you have typed the last
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	835 line).
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	836
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	837 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	838 The {\tt print} statement writes the value of the expression(s) it is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	839 given. It differs from just writing the expression you want to write
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	840 (as we did earlier in the calculator examples) in the way it handles
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	841 multiple expressions and strings. Strings are printed without quotes,
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	842 and a space is inserted between items, so you can format things nicely,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	843 like this:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	844
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	845 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	846 >>> i = 256*256
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	847 >>> print 'The value of i is', i
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	848 The value of i is 65536
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	849 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	850 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	851 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	852 A trailing comma avoids the newline after the output:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	853
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	854 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	855 >>> a, b = 0, 1
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	856 >>> while b < 1000:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	857 ... print b,
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	858 ... a, b = b, a+b
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	859 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	860 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	861 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	862 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	863 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	864 Note that the interpreter inserts a newline before it prints the next
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	865 prompt if the last line was not completed.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	866
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	867 \end{itemize}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	868
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	869
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	870 \chapter{More Control Flow Tools}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	871
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	872 Besides the {\tt while} statement just introduced, Python knows the
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	873 usual control flow statements known from other languages, with some
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	874 twists.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	875
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	876 \section{If Statements}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	877
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	878 Perhaps the most well-known statement type is the {\tt if} statement.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	879 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	880
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	881 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	882 >>> if x < 0:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	883 ... x = 0
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	884 ... print 'Negative changed to zero'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	885 ... elif x == 0:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	886 ... print 'Zero'
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	887 ... elif x == 1:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	888 ... print 'Single'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	889 ... else:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	890 ... print 'More'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	891 ...
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	892 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	893 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	894 There can be zero or more {\tt elif} parts, and the {\tt else} part is
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	895 optional. The keyword `{\tt elif}' is short for `{\tt else if}', and is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	896 useful to avoid excessive indentation. An {\tt if...elif...elif...}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	897 sequence is a substitute for the {\em switch} or {\em case} statements
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	898 found in other languages.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	899
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	900 \section{For Statements}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	901
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	902 The {\tt for} statement in Python differs a bit from what you may be
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	903 used to in C or Pascal. Rather than always iterating over an
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	904 arithmetic progression of numbers (like in Pascal), or leaving the user
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	905 completely free in the iteration test and step (as C), Python's {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	906 for} statement iterates over the items of any sequence (e.g., a list
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	907 or a string), in the order that they appear in the sequence. For
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	908 example (no pun intended):
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	909
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	910 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	911 >>> # Measure some strings:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	912 ... a = ['cat', 'window', 'defenestrate']
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	913 >>> for x in a:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	914 ... print x, len(x)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	915 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	916 cat 3
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	917 window 6
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	918 defenestrate 12
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	919 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	920 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	921 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	922 It is not safe to modify the sequence being iterated over in the loop
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	923 (this can only happen for mutable sequence types, i.e., lists). If
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	924 you need to modify the list you are iterating over, e.g., duplicate
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	925 selected items, you must iterate over a copy. The slice notation
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	926 makes this particularly convenient:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	927
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	928 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	929 >>> for x in a[:]: # make a slice copy of the entire list
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	930 ... if len(x) > 6: a.insert(0, x)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	931 ...
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	932 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	933 ['defenestrate', 'cat', 'window', 'defenestrate']
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	934 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	935 \end{verbatim}\ecode
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	936
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	937 \section{The {\tt range()} Function}
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	938
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	939 If you do need to iterate over a sequence of numbers, the built-in
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	940 function {\tt range()} comes in handy. It generates lists containing
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	941 arithmetic progressions, e.g.:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	942
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	943 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	944 >>> range(10)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	945 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	946 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	947 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	948 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	949 The given end point is never part of the generated list; {\tt range(10)}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	950 generates a list of 10 values, exactly the legal indices for items of a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	951 sequence of length 10. It is possible to let the range start at another
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	952 number, or to specify a different increment (even negative):
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	953
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	954 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	955 >>> range(5, 10)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	956 [5, 6, 7, 8, 9]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	957 >>> range(0, 10, 3)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	958 [0, 3, 6, 9]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	959 >>> range(-10, -100, -30)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	960 [-10, -40, -70]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	961 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	962 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	963 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	964 To iterate over the indices of a sequence, combine {\tt range()} and
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	965 {\tt len()} as follows:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	966
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	967 \bcode\begin{verbatim}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	968 >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	969 >>> for i in range(len(a)):
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	970 ... print i, a[i]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	971 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	972 0 Mary
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	973 1 had
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	974 2 a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	975 3 little
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	976 4 lamb
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	977 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	978 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	979
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	980 \section{Break and Continue Statements, and Else Clauses on Loops}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	981
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	982 The {\tt break} statement, like in C, breaks out of the smallest
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	983 enclosing {\tt for} or {\tt while} loop.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	984
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	985 The {\tt continue} statement, also borrowed from C, continues with the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	986 next iteration of the loop.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	987
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	988 Loop statements may have an {\tt else} clause; it is executed when the
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	989 loop terminates through exhaustion of the list (with {\tt for}) or when
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	990 the condition becomes false (with {\tt while}), but not when the loop is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	991 terminated by a {\tt break} statement. This is exemplified by the
2013 dc9b6316b9b3 typos Guido van Rossum <guido@python.org> parents: 1947 diff changeset	992 following loop, which searches for prime numbers:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	993
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	994 \bcode\begin{verbatim}
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	995 >>> for n in range(2, 10):
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	996 ... for x in range(2, n):
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	997 ... if n % x == 0:
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	998 ... print n, 'equals', x, '*', n/x
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	999 ... break
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1000 ... else:
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1001 ... print n, 'is a prime number'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1002 ...
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1003 2 is a prime number
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1004 3 is a prime number
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1005 4 equals 2 * 2
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1006 5 is a prime number
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1007 6 equals 2 * 3
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1008 7 is a prime number
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1009 8 equals 2 * 4
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1010 9 equals 3 * 3
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1011 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1012 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1013
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1014 \section{Pass Statements}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1015
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1016 The {\tt pass} statement does nothing.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1017 It can be used when a statement is required syntactically but the
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1018 program requires no action.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1019 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1020
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1021 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1022 >>> while 1:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1023 ... pass # Busy-wait for keyboard interrupt
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1024 ...
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1025 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1026
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1027 \section{Defining Functions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1028
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1029 We can create a function that writes the Fibonacci series to an
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1030 arbitrary boundary:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1031
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1032 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1033 >>> def fib(n): # write Fibonacci series up to n
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1034 ... "Print a Fibonacci series up to n"
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1035 ... a, b = 0, 1
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	1036 ... while b < n:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1037 ... print b,
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1038 ... a, b = b, a+b
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1039 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1040 >>> # Now call the function we just defined:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1041 ... fib(2000)
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1042 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1043 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1044 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1045 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1046 The keyword {\tt def} introduces a function {\em definition}. It must
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1047 be followed by the function name and the parenthesized list of formal
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1048 parameters. The statements that form the body of the function start
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1049 at the next line, indented by a tab stop. The first statement of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1050 function body can optionally be a string literal; this string literal
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1051 is the function's documentation string, or \dfn{docstring}. There are
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1052 tools which use docstrings to automatically produce printed
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1053 documentation, or to let the user interactively browse through code;
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1054 it's good practice to include docstrings in code that you write, so
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1055 try to make a habit of it.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1056
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1057 The {\em execution} of a function introduces a new symbol table used
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1058 for the local variables of the function. More precisely, all variable
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1059 assignments in a function store the value in the local symbol table;
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1060 whereas variable references first look in the local symbol table, then
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1061 in the global symbol table, and then in the table of built-in names.
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1062 Thus,
2013 dc9b6316b9b3 typos Guido van Rossum <guido@python.org> parents: 1947 diff changeset	1063 global variables cannot be directly assigned a value within a
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1064 function (unless named in a {\tt global} statement), although
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1065 they may be referenced.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1066
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1067 The actual parameters (arguments) to a function call are introduced in
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1068 the local symbol table of the called function when it is called; thus,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1069 arguments are passed using {\em call\ by\ value}.%
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1070 \footnote{
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1071 Actually, {\em call by object reference} would be a better
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1072 description, since if a mutable object is passed, the caller
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1073 will see any changes the callee makes to it (e.g., items
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1074 inserted into a list).
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1075 }
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1076 When a function calls another function, a new local symbol table is
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1077 created for that call.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1078
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1079 A function definition introduces the function name in the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1080 current
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1081 symbol table. The value
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1082 of the function name
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1083 has a type that is recognized by the interpreter as a user-defined
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1084 function. This value can be assigned to another name which can then
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1085 also be used as a function. This serves as a general renaming
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1086 mechanism:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1087
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1088 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1089 >>> fib
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1090 <function object at 10042ed0>
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1091 >>> f = fib
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1092 >>> f(100)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1093 1 1 2 3 5 8 13 21 34 55 89
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1094 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1095 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1096 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1097 You might object that {\tt fib} is not a function but a procedure. In
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1098 Python, like in C, procedures are just functions that don't return a
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1099 value. In fact, technically speaking, procedures do return a value,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1100 albeit a rather boring one. This value is called {\tt None} (it's a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1101 built-in name). Writing the value {\tt None} is normally suppressed by
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1102 the interpreter if it would be the only value written. You can see it
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1103 if you really want to:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1104
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1105 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1106 >>> print fib(0)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1107 None
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1108 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1109 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1110 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1111 It is simple to write a function that returns a list of the numbers of
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1112 the Fibonacci series, instead of printing it:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1113
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1114 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1115 >>> def fib2(n): # return Fibonacci series up to n
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1116 ... "Return a list containing the Fibonacci series up to n"
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1117 ... result = []
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1118 ... a, b = 0, 1
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	1119 ... while b < n:
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1120 ... result.append(b) # see below
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1121 ... a, b = b, a+b
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1122 ... return result
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1123 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1124 >>> f100 = fib2(100) # call it
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1125 >>> f100 # write the result
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1126 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1127 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1128 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1129 %
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	1130 This example, as usual, demonstrates some new Python features:
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1131
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1132 \begin{itemize}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1133
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1134 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1135 The {\tt return} statement returns with a value from a function. {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1136 return} without an expression argument is used to return from the middle
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1137 of a procedure (falling off the end also returns from a procedure), in
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1138 which case the {\tt None} value is returned.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1139
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1140 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1141 The statement {\tt result.append(b)} calls a {\em method} of the list
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1142 object {\tt result}. A method is a function that `belongs' to an
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1143 object and is named {\tt obj.methodname}, where {\tt obj} is some
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1144 object (this may be an expression), and {\tt methodname} is the name
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1145 of a method that is defined by the object's type. Different types
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1146 define different methods. Methods of different types may have the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1147 same name without causing ambiguity. (It is possible to define your
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1148 own object types and methods, using {\em classes}, as discussed later
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1149 in this tutorial.)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1150 The method {\tt append} shown in the example, is defined for
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1151 list objects; it adds a new element at the end of the list. In this
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1152 example
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1153 it is equivalent to {\tt result = result + [b]}, but more efficient.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1154
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1155 \end{itemize}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1156
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1157 \section{More on Defining Functions}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1158
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1159 It is also possible to define functions with a variable number of
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1160 arguments. There are three forms, which can be combined.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1161
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1162 \subsection{Default Argument Values}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1163
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1164 The most useful form is to specify a default value for one or more
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1165 arguments. This creates a function that can be called with fewer
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1166 arguments than it is defined, e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1167
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1168 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1169 def ask_ok(prompt, retries = 4, complaint = 'Yes or no, please!'):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1170 while 1:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1171 ok = raw_input(prompt)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1172 if ok in ('y', 'ye', 'yes'): return 1
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1173 if ok in ('n', 'no', 'nop', 'nope'): return 0
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1174 retries = retries - 1
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1175 if retries < 0: raise IOError, 'refusenik user'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1176 print complaint
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1177 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1178
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1179 This function can be called either like this:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1180 \verb\ask_ok('Do you really want to quit?')\ or like this:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1181 \verb\ask_ok('OK to overwrite the file?', 2)\.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1182
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1183 The default values are evaluated at the point of function definition
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1184 in the {\em defining} scope, so that e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1185
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1186 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1187 i = 5
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1188 def f(arg = i): print arg
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1189 i = 6
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1190 f()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1191 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1192
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1193 will print \verb\5\.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1194
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1195 \subsection{Keyword Arguments}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1196
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1197 Functions can also be called using
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1198 keyword arguments of the form \code{\var{keyword} = \var{value}}. For
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1199 instance, the following function:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1200
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1201 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1202 def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1203 print "-- This parrot wouldn't", action,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1204 print "if you put", voltage, "Volts through it."
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1205 print "-- Lovely plumage, the", type
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1206 print "-- It's", state, "!"
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1207 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1208
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1209 could be called in any of the following ways:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1210
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1211 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1212 parrot(1000)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1213 parrot(action = 'VOOOOOM', voltage = 1000000)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1214 parrot('a thousand', state = 'pushing up the daisies')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1215 parrot('a million', 'bereft of life', 'jump')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1216 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1217
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1218 but the following calls would all be invalid:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1219
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1220 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1221 parrot() # required argument missing
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1222 parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1223 parrot(110, voltage=220) # duplicate value for argument
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1224 parrot(actor='John Cleese') # unknown keyword
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1225 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1226
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1227 In general, an argument list must have any positional arguments
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1228 followed by any keyword arguments, where the keywords must be chosen
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1229 from the formal parameter names. It's not important whether a formal
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1230 parameter has a default value or not. No argument must receive a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1231 value more than once --- formal parameter names corresponding to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1232 positional arguments cannot be used as keywords in the same calls.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1233
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1234 When a final formal parameter of the form \code{**\var{name}} is
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1235 present, it receives a dictionary containing all keyword arguments
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1236 whose keyword doesn't correspond to a formal parameter. This may be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1237 combined with a formal parameter of the form \code{*\var{name}}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1238 (described in the next subsection) which receives a tuple containing
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1239 the positional arguments beyond the formal parameter list.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1240 (\code{\var{name}} must occur before \code{*\var{name}}.) For
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1241 example, if we define a function like this:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1242
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1243 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1244 def cheeseshop(kind, arguments, *keywords):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1245 print "-- Do you have any", kind, '?'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1246 print "-- I'm sorry, we're all out of", kind
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1247 for arg in arguments: print arg
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1248 print '-'*40
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1249 for kw in keywords.keys(): print kw, ':', keywords[kw]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1250 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1251
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1252 It could be called like this:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1253
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1254 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1255 cheeseshop('Limburger', "It's very runny, sir.",
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1256 "It's really very, VERY runny, sir.",
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1257 client='John Cleese',
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1258 shopkeeper='Michael Palin',
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1259 sketch='Cheese Shop Sketch')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1260 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1261
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1262 and of course it would print:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1263
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1264 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1265 -- Do you have any Limburger ?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1266 -- I'm sorry, we're all out of Limburger
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1267 It's very runny, sir.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1268 It's really very, VERY runny, sir.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1269 ----------------------------------------
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1270 client : John Cleese
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1271 shopkeeper : Michael Palin
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1272 sketch : Cheese Shop Sketch
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1273 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1274
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1275 \subsection{Arbitrary Argument Lists}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1276
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1277 Finally, the least frequently used option is to specify that a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1278 function can be called with an arbitrary number of arguments. These
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1279 arguments will be wrapped up in a tuple. Before the variable number
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1280 of arguments, zero or more normal arguments may occur.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1281
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1282 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1283 def fprintf(file, format, *args):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1284 file.write(format % args)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1285 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1286
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1287 \chapter{Data Structures}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1288
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1289 This chapter describes some things you've learned about already in
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1290 more detail, and adds some new things as well.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1291
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1292 \section{More on Lists}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1293
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1294 The list data type has some more methods. Here are all of the methods
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1295 of lists objects:
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1296
121 0c25faf4a6a4 Small changes. Use description instead of list env. Guido van Rossum <guido@python.org> parents: 112 diff changeset	1297 \begin{description}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1298
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1299 \item[{\tt insert(i, x)}]
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1300 Insert an item at a given position. The first argument is the index of
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1301 the element before which to insert, so {\tt a.insert(0, x)} inserts at
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1302 the front of the list, and {\tt a.insert(len(a), x)} is equivalent to
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1303 {\tt a.append(x)}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1304
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1305 \item[{\tt append(x)}]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1306 Equivalent to {\tt a.insert(len(a), x)}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1307
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1308 \item[{\tt index(x)}]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1309 Return the index in the list of the first item whose value is {\tt x}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1310 It is an error if there is no such item.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1311
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1312 \item[{\tt remove(x)}]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1313 Remove the first item from the list whose value is {\tt x}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1314 It is an error if there is no such item.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1315
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1316 \item[{\tt sort()}]
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1317 Sort the items of the list, in place.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1318
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1319 \item[{\tt reverse()}]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1320 Reverse the elements of the list, in place.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1321
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1322 \item[{\tt count(x)}]
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1323 Return the number of times {\tt x} appears in the list.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1324
121 0c25faf4a6a4 Small changes. Use description instead of list env. Guido van Rossum <guido@python.org> parents: 112 diff changeset	1325 \end{description}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1326
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1327 An example that uses all list methods:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1328
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1329 \bcode\begin{verbatim}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1330 >>> a = [66.6, 333, 333, 1, 1234.5]
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1331 >>> print a.count(333), a.count(66.6), a.count('x')
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1332 2 1 0
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1333 >>> a.insert(2, -1)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1334 >>> a.append(333)
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1335 >>> a
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1336 [66.6, 333, -1, 333, 1, 1234.5, 333]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1337 >>> a.index(333)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1338 1
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1339 >>> a.remove(333)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1340 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1341 [66.6, -1, 333, 1, 1234.5, 333]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1342 >>> a.reverse()
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1343 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1344 [333, 1234.5, 1, 333, -1, 66.6]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1345 >>> a.sort()
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1346 >>> a
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1347 [-1, 1, 66.6, 333, 333, 1234.5]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1348 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1349 \end{verbatim}\ecode
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1350
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1351 \subsection{Functional Programming Tools}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1352
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1353 There are three built-in functions that are very useful when used with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1354 lists: \verb\filter\, \verb\map\, and \verb\reduce\.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1355
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1356 \verb\filter(function, sequence)\ returns a sequence (of the same
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1357 type, if possible) consisting of those items from the sequence for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1358 which \verb\function(item)\ is true. For example, to compute some
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1359 primes:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1360
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1361 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1362 >>> def f(x): return x%2 != 0 and x%3 != 0
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1363 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1364 >>> filter(f, range(2, 25))
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1365 [5, 7, 11, 13, 17, 19, 23]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1366 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1367 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1368
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1369 \verb\map(function, sequence)\ calls \verb\function(item)\ for each of
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1370 the sequence's items and returns a list of the return values. For
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1371 example, to compute some cubes:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1372
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1373 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1374 >>> def cube(x): return xxx
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1375 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1376 >>> map(cube, range(1, 11))
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1377 [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1378 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1379 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1380
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1381 More than one sequence may be passed; the function must then have as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1382 many arguments as there are sequences and is called with the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1383 corresponding item from each sequence (or \verb\None\ if some sequence
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1384 is shorter than another). If \verb\None\ is passed for the function,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1385 a function returning its argument(s) is substituted.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1386
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1387 Combining these two special cases, we see that
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1388 \verb\map(None, list1, list2)\ is a convenient way of turning a pair
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1389 of lists into a list of pairs. For example:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1390
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1391 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1392 >>> seq = range(8)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1393 >>> def square(x): return x*x
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1394 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1395 >>> map(None, seq, map(square, seq))
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1396 [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1397 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1398 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1399
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1400 \verb\reduce(func, sequence)\ returns a single value constructed
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1401 by calling the binary function \verb\func\ on the first two items of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1402 sequence, then on the result and the next item, and so on. For
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1403 example, to compute the sum of the numbers 1 through 10:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1404
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1405 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1406 >>> def add(x,y): return x+y
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1407 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1408 >>> reduce(add, range(1, 11))
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1409 55
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1410 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1411 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1412
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1413 If there's only one item in the sequence, its value is returned; if
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1414 the sequence is empty, an exception is raised.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1415
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1416 A third argument can be passed to indicate the starting value. In this
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1417 case the starting value is returned for an empty sequence, and the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1418 function is first applied to the starting value and the first sequence
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1419 item, then to the result and the next item, and so on. For example,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1420
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1421 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1422 >>> def sum(seq):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1423 ... def add(x,y): return x+y
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1424 ... return reduce(add, seq, 0)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1425 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1426 >>> sum(range(1, 11))
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1427 55
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1428 >>> sum([])
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1429 0
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1430 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1431 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1432
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1433 \section{The {\tt del} statement}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1434
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1435 There is a way to remove an item from a list given its index instead
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1436 of its value: the {\tt del} statement. This can also be used to
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1437 remove slices from a list (which we did earlier by assignment of an
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1438 empty list to the slice). For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1439
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1440 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1441 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1442 [-1, 1, 66.6, 333, 333, 1234.5]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1443 >>> del a[0]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1444 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1445 [1, 66.6, 333, 333, 1234.5]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1446 >>> del a[2:4]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1447 >>> a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1448 [1, 66.6, 1234.5]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1449 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1450 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1451 %
73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1452 {\tt del} can also be used to delete entire variables:
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1453
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1454 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1455 >>> del a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1456 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1457 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1458 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1459 Referencing the name {\tt a} hereafter is an error (at least until
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1460 another value is assigned to it). We'll find other uses for {\tt del}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1461 later.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1462
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1463 \section{Tuples and Sequences}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1464
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1465 We saw that lists and strings have many common properties, e.g.,
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1466 indexing and slicing operations. They are two examples of {\em
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1467 sequence} data types. Since Python is an evolving language, other
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1468 sequence data types may be added. There is also another standard
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1469 sequence data type: the {\em tuple}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1470
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1471 A tuple consists of a number of values separated by commas, for
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1472 instance:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1473
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1474 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1475 >>> t = 12345, 54321, 'hello!'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1476 >>> t[0]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1477 12345
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1478 >>> t
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1479 (12345, 54321, 'hello!')
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1480 >>> # Tuples may be nested:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1481 ... u = t, (1, 2, 3, 4, 5)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1482 >>> u
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1483 ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1484 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1485 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1486 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1487 As you see, on output tuples are alway enclosed in parentheses, so
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1488 that nested tuples are interpreted correctly; they may be input with
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1489 or without surrounding parentheses, although often parentheses are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1490 necessary anyway (if the tuple is part of a larger expression).
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1491
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1492 Tuples have many uses, e.g., (x, y) coordinate pairs, employee records
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1493 from a database, etc. Tuples, like strings, are immutable: it is not
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1494 possible to assign to the individual items of a tuple (you can
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1495 simulate much of the same effect with slicing and concatenation,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1496 though).
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1497
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1498 A special problem is the construction of tuples containing 0 or 1
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1499 items: the syntax has some extra quirks to accommodate these. Empty
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1500 tuples are constructed by an empty pair of parentheses; a tuple with
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1501 one item is constructed by following a value with a comma
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1502 (it is not sufficient to enclose a single value in parentheses).
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1503 Ugly, but effective. For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1504
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1505 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1506 >>> empty = ()
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1507 >>> singleton = 'hello', # <-- note trailing comma
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1508 >>> len(empty)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1509 0
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1510 >>> len(singleton)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1511 1
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1512 >>> singleton
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1513 ('hello',)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1514 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1515 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1516 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1517 The statement {\tt t = 12345, 54321, 'hello!'} is an example of {\em
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1518 tuple packing}: the values {\tt 12345}, {\tt 54321} and {\tt 'hello!'}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1519 are packed together in a tuple. The reverse operation is also
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1520 possible, e.g.:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1521
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1522 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1523 >>> x, y, z = t
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1524 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1525 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1526 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1527 This is called, appropriately enough, {\em tuple unpacking}. Tuple
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1528 unpacking requires that the list of variables on the left has the same
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1529 number of elements as the length of the tuple. Note that multiple
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1530 assignment is really just a combination of tuple packing and tuple
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1531 unpacking!
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1532
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1533 Occasionally, the corresponding operation on lists is useful: {\em list
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1534 unpacking}. This is supported by enclosing the list of variables in
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1535 square brackets:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1536
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1537 \bcode\begin{verbatim}
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	1538 >>> a = ['spam', 'eggs', 100, 1234]
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1539 >>> [a1, a2, a3, a4] = a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1540 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1541 \end{verbatim}\ecode
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1542
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1543 \section{Dictionaries}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1544
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1545 Another useful data type built into Python is the {\em dictionary}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1546 Dictionaries are sometimes found in other languages as ``associative
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1547 memories'' or ``associative arrays''. Unlike sequences, which are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1548 indexed by a range of numbers, dictionaries are indexed by {\em keys},
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1549 which can be any non-mutable type; strings and numbers can always be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1550 keys. Tuples can be used as keys if they contain only strings,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1551 numbers, or tuples. You can't use lists as keys, since lists can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1552 modified in place using their \code{append()} method.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1553
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1554 It is best to think of a dictionary as an unordered set of
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1555 {\em key:value} pairs, with the requirement that the keys are unique
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1556 (within one dictionary).
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1557 A pair of braces creates an empty dictionary: \verb/{}/.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1558 Placing a comma-separated list of key:value pairs within the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1559 braces adds initial key:value pairs to the dictionary; this is also the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1560 way dictionaries are written on output.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1561
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1562 The main operations on a dictionary are storing a value with some key
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1563 and extracting the value given the key. It is also possible to delete
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1564 a key:value pair
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1565 with {\tt del}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1566 If you store using a key that is already in use, the old value
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1567 associated with that key is forgotten. It is an error to extract a
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1568 value using a non-existent key.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1569
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1570 The {\tt keys()} method of a dictionary object returns a list of all the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1571 keys used in the dictionary, in random order (if you want it sorted,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1572 just apply the {\tt sort()} method to the list of keys). To check
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1573 whether a single key is in the dictionary, use the \verb/has_key()/
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1574 method of the dictionary.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1575
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1576 Here is a small example using a dictionary:
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1577
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1578 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1579 >>> tel = {'jack': 4098, 'sape': 4139}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1580 >>> tel['guido'] = 4127
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1581 >>> tel
440 e2db3341d686 Fixed dictionary example to use commas instead of semicolons. Guido van Rossum <guido@python.org> parents: 342 diff changeset	1582 {'sape': 4139, 'guido': 4127, 'jack': 4098}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1583 >>> tel['jack']
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1584 4098
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1585 >>> del tel['sape']
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1586 >>> tel['irv'] = 4127
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1587 >>> tel
440 e2db3341d686 Fixed dictionary example to use commas instead of semicolons. Guido van Rossum <guido@python.org> parents: 342 diff changeset	1588 {'guido': 4127, 'irv': 4127, 'jack': 4098}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1589 >>> tel.keys()
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1590 ['guido', 'irv', 'jack']
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1591 >>> tel.has_key('guido')
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1592 1
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1593 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1594 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1595
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1596 \section{More on Conditions}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1597
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1598 The conditions used in {\tt while} and {\tt if} statements above can
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1599 contain other operators besides comparisons.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1600
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1601 The comparison operators {\tt in} and {\tt not in} check whether a value
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1602 occurs (does not occur) in a sequence. The operators {\tt is} and {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1603 is not} compare whether two objects are really the same object; this
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1604 only matters for mutable objects like lists. All comparison operators
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1605 have the same priority, which is lower than that of all numerical
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1606 operators.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1607
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	1608 Comparisons can be chained: e.g., {\tt a < b == c} tests whether {\tt a}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1609 is less than {\tt b} and moreover {\tt b} equals {\tt c}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1610
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1611 Comparisons may be combined by the Boolean operators {\tt and} and {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1612 or}, and the outcome of a comparison (or of any other Boolean
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1613 expression) may be negated with {\tt not}. These all have lower
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1614 priorities than comparison operators again; between them, {\tt not} has
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1615 the highest priority, and {\tt or} the lowest, so that
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1616 {\tt A and not B or C} is equivalent to {\tt (A and (not B)) or C}. Of
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1617 course, parentheses can be used to express the desired composition.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1618
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1619 The Boolean operators {\tt and} and {\tt or} are so-called {\em
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1620 shortcut} operators: their arguments are evaluated from left to right,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1621 and evaluation stops as soon as the outcome is determined. E.g., if
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1622 {\tt A} and {\tt C} are true but {\tt B} is false, {\tt A and B and C}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1623 does not evaluate the expression C. In general, the return value of a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1624 shortcut operator, when used as a general value and not as a Boolean, is
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1625 the last evaluated argument.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1626
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1627 It is possible to assign the result of a comparison or other Boolean
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1628 expression to a variable. For example,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1629
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1630 \bcode\begin{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1631 >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1632 >>> non_null = string1 or string2 or string3
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1633 >>> non_null
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1634 'Trondheim'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1635 >>>
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1636 \end{verbatim}\ecode
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1637 %
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1638 Note that in Python, unlike C, assignment cannot occur inside expressions.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1639
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1640 \section{Comparing Sequences and Other Types}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1641
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1642 Sequence objects may be compared to other objects with the same
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1643 sequence type. The comparison uses {\em lexicographical} ordering:
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1644 first the first two items are compared, and if they differ this
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1645 determines the outcome of the comparison; if they are equal, the next
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1646 two items are compared, and so on, until either sequence is exhausted.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1647 If two items to be compared are themselves sequences of the same type,
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1648 the lexicographical comparison is carried out recursively. If all
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1649 items of two sequences compare equal, the sequences are considered
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1650 equal. If one sequence is an initial subsequence of the other, the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1651 shorted sequence is the smaller one. Lexicographical ordering for
2550 0f6ff45bd816 replace ASCII by macro call Guido van Rossum <guido@python.org> parents: 2453 diff changeset	1652 strings uses the \ASCII{} ordering for individual characters. Some
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1653 examples of comparisons between sequences with the same types:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1654
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1655 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1656 (1, 2, 3) < (1, 2, 4)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1657 [1, 2, 3] < [1, 2, 4]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1658 'ABC' < 'C' < 'Pascal' < 'Python'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1659 (1, 2, 3, 4) < (1, 2, 4)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1660 (1, 2) < (1, 2, -1)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1661 (1, 2, 3) = (1.0, 2.0, 3.0)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1662 (1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1663 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1664 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1665 Note that comparing objects of different types is legal. The outcome
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1666 is deterministic but arbitrary: the types are ordered by their name.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1667 Thus, a list is always smaller than a string, a string is always
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1668 smaller than a tuple, etc. Mixed numeric types are compared according
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1669 to their numeric value, so 0 equals 0.0, etc.%
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1670 \footnote{
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1671 The rules for comparing objects of different types should
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1672 not be relied upon; they may change in a future version of
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1673 the language.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1674 }
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1675
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	1676
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1677 \chapter{Modules}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1678
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	1679 If you quit from the Python interpreter and enter it again, the
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1680 definitions you have made (functions and variables) are lost.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1681 Therefore, if you want to write a somewhat longer program, you are
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1682 better off using a text editor to prepare the input for the interpreter
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1683 and running it with that file as input instead. This is known as creating a
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1684 {\em script}. As your program gets longer, you may want to split it
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1685 into several files for easier maintenance. You may also want to use a
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1686 handy function that you've written in several programs without copying
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1687 its definition into each program.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1688
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	1689 To support this, Python has a way to put definitions in a file and use
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1690 them in a script or in an interactive instance of the interpreter.
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1691 Such a file is called a {\em module}; definitions from a module can be
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1692 {\em imported} into other modules or into the {\em main} module (the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1693 collection of variables that you have access to in a script
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1694 executed at the top level
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1695 and in calculator mode).
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1696
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1697 A module is a file containing Python definitions and statements. The
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1698 file name is the module name with the suffix {\tt .py} appended. Within
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1699 a module, the module's name (as a string) is available as the value of
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1700 the global variable {\tt __name__}. For instance, use your favorite text
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1701 editor to create a file called {\tt fibo.py} in the current directory
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1702 with the following contents:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1703
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1704 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1705 # Fibonacci numbers module
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1706
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1707 def fib(n): # write Fibonacci series up to n
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1708 a, b = 0, 1
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	1709 while b < n:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1710 print b,
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1711 a, b = b, a+b
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1712
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1713 def fib2(n): # return Fibonacci series up to n
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1714 result = []
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1715 a, b = 0, 1
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	1716 while b < n:
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1717 result.append(b)
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1718 a, b = b, a+b
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1719 return result
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1720 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1721 %
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	1722 Now enter the Python interpreter and import this module with the
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1723 following command:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1724
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1725 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1726 >>> import fibo
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1727 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1728 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1729 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1730 This does not enter the names of the functions defined in
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1731 {\tt fibo}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1732 directly in the current symbol table; it only enters the module name
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1733 {\tt fibo}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1734 there.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1735 Using the module name you can access the functions:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1736
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1737 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1738 >>> fibo.fib(1000)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1739 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1740 >>> fibo.fib2(100)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1741 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1742 >>> fibo.__name__
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1743 'fibo'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1744 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1745 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1746 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1747 If you intend to use a function often you can assign it to a local name:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1748
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1749 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1750 >>> fib = fibo.fib
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1751 >>> fib(500)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1752 1 1 2 3 5 8 13 21 34 55 89 144 233 377
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1753 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1754 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1755
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1756
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1757 \section{More on Modules}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1758
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1759 A module can contain executable statements as well as function
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1760 definitions.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1761 These statements are intended to initialize the module.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1762 They are executed only the
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	1763 {\em first}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1764 time the module is imported somewhere.%
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1765 \footnote{
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1766 In fact function definitions are also `statements' that are
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1767 `executed'; the execution enters the function name in the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1768 module's global symbol table.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1769 }
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1770
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1771 Each module has its own private symbol table, which is used as the
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1772 global symbol table by all functions defined in the module.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1773 Thus, the author of a module can use global variables in the module
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1774 without worrying about accidental clashes with a user's global
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1775 variables.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1776 On the other hand, if you know what you are doing you can touch a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1777 module's global variables with the same notation used to refer to its
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1778 functions,
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1779 {\tt modname.itemname}.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1780
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1781 Modules can import other modules.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1782 It is customary but not required to place all
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1783 {\tt import}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1784 statements at the beginning of a module (or script, for that matter).
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1785 The imported module names are placed in the importing module's global
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1786 symbol table.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1787
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1788 There is a variant of the
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1789 {\tt import}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1790 statement that imports names from a module directly into the importing
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1791 module's symbol table.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1792 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1793
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1794 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1795 >>> from fibo import fib, fib2
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1796 >>> fib(500)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1797 1 1 2 3 5 8 13 21 34 55 89 144 233 377
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1798 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1799 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1800 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1801 This does not introduce the module name from which the imports are taken
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1802 in the local symbol table (so in the example, {\tt fibo} is not
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1803 defined).
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1804
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1805 There is even a variant to import all names that a module defines:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1806
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1807 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1808 >>> from fibo import *
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1809 >>> fib(500)
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1810 1 1 2 3 5 8 13 21 34 55 89 144 233 377
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1811 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1812 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1813 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1814 This imports all names except those beginning with an underscore
697 7c06bf15fd2a _ can now be a normal character. Guido van Rossum <guido@python.org> parents: 670 diff changeset	1815 ({\tt _}).
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1816
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1817 \subsection{The Module Search Path}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1818
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1819 When a module named {\tt spam} is imported, the interpreter searches
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1820 for a file named {\tt spam.py} in the current directory,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1821 and then in the list of directories specified by
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1822 the environment variable {\tt PYTHONPATH}. This has the same syntax as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1823 the \UNIX{} shell variable {\tt PATH}, i.e., a list of colon-separated
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1824 directory names. When {\tt PYTHONPATH} is not set, or when the file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1825 is not found there, the search continues in an installation-dependent
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1826 default path, usually {\tt .:/usr/local/lib/python}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1827
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1828 Actually, modules are searched in the list of directories given by the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1829 variable {\tt sys.path} which is initialized from the directory
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1830 containing the input script (or the current directory), {\tt
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1831 PYTHONPATH} and the installation-dependent default. This allows
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1832 Python programs that know what they're doing to modify or replace the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1833 module search path. See the section on Standard Modules later.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1834
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1835 \subsection{``Compiled'' Python files}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1836
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1837 As an important speed-up of the start-up time for short programs that
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1838 use a lot of standard modules, if a file called {\tt spam.pyc} exists
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1839 in the directory where {\tt spam.py} is found, this is assumed to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1840 contain an already-``compiled'' version of the module {\tt spam}. The
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1841 modification time of the version of {\tt spam.py} used to create {\tt
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1842 spam.pyc} is recorded in {\tt spam.pyc}, and the file is ignored if
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1843 these don't match.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1844
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1845 Normally, you don't need to do anything to create the {\tt spam.pyc} file.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1846 Whenever {\tt spam.py} is successfully compiled, an attempt is made to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1847 write the compiled version to {\tt spam.pyc}. It is not an error if
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1848 this attempt fails; if for any reason the file is not written
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1849 completely, the resulting {\tt spam.pyc} file will be recognized as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1850 invalid and thus ignored later. The contents of the {\tt spam.pyc}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1851 file is platform independent, so a Python module directory can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1852 shared by machines of different architectures. (Tip for experts:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1853 the module {\tt compileall} creates {\tt .pyc} files for all modules.)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1854
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1855 XXX Should optimization with -O be covered here?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1856
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1857 \section{Standard Modules}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1858
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	1859 Python comes with a library of standard modules, described in a separate
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1860 document (Python Library Reference). Some modules are built into the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1861 interpreter; these provide access to operations that are not part of the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1862 core of the language but are nevertheless built in, either for
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1863 efficiency or to provide access to operating system primitives such as
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1864 system calls. The set of such modules is a configuration option; e.g.,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1865 the {\tt amoeba} module is only provided on systems that somehow support
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1866 Amoeba primitives. One particular module deserves some attention: {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1867 sys}, which is built into every Python interpreter. The variables {\tt
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1868 sys.ps1} and {\tt sys.ps2} define the strings used as primary and
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1869 secondary prompts:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1870
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1871 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1872 >>> import sys
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1873 >>> sys.ps1
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1874 '>>> '
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1875 >>> sys.ps2
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1876 '... '
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1877 >>> sys.ps1 = 'C> '
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1878 C> print 'Yuck!'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1879 Yuck!
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1880 C>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1881 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1882 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1883 These two variables are only defined if the interpreter is in
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1884 interactive mode.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1885
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1886 The variable
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1887 {\tt sys.path}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1888 is a list of strings that determine the interpreter's search path for
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1889 modules.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1890 It is initialized to a default path taken from the environment variable
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1891 {\tt PYTHONPATH},
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1892 or from a built-in default if
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1893 {\tt PYTHONPATH}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1894 is not set.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1895 You can modify it using standard list operations, e.g.:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1896
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1897 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1898 >>> import sys
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1899 >>> sys.path.append('/ufs/guido/lib/python')
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1900 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	1901 \end{verbatim}\ecode
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1902
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1903 \section{The {\tt dir()} function}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1904
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1905 The built-in function {\tt dir} is used to find out which names a module
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1906 defines. It returns a sorted list of strings:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1907
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1908 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1909 >>> import fibo, sys
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1910 >>> dir(fibo)
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1911 ['__name__', 'fib', 'fib2']
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1912 >>> dir(sys)
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1913 ['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1914 'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1915 'stderr', 'stdin', 'stdout', 'version']
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1916 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1917 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1918 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1919 Without arguments, {\tt dir()} lists the names you have defined currently:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1920
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1921 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1922 >>> a = [1, 2, 3, 4, 5]
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1923 >>> import fibo, sys
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1924 >>> fib = fibo.fib
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1925 >>> dir()
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1926 ['__name__', 'a', 'fib', 'fibo', 'sys']
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1927 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1928 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1929 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1930 Note that it lists all types of names: variables, modules, functions, etc.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1931
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1932 {\tt dir()} does not list the names of built-in functions and variables.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1933 If you want a list of those, they are defined in the standard module
1374 89d7d5e136ad * lib3.tex (module string): added rindex(). Guido van Rossum <guido@python.org> parents: 1283 diff changeset	1934 {\tt __builtin__}:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1935
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1936 \bcode\begin{verbatim}
1374 89d7d5e136ad * lib3.tex (module string): added rindex(). Guido van Rossum <guido@python.org> parents: 1283 diff changeset	1937 >>> import __builtin__
89d7d5e136ad * lib3.tex (module string): added rindex(). Guido van Rossum <guido@python.org> parents: 1283 diff changeset	1938 >>> dir(__builtin__)
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1939 ['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1940 'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1941 'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1942 'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1943 'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1944 'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1945 'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1946 'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input',
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1947 'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange']
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1948 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1949 \end{verbatim}\ecode
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1950
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	1951
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1952 \chapter{Input and Output}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1953
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1954 There are several ways to present the output of a program; data can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1955 printed in a human-readable form, or written to a file for future use.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1956 This chapter will discuss some of the possibilities.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1957
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1958 \section{Fancier Output Formatting}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1959 So far we've encountered two ways of writing values: {\em expression
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1960 statements} and the {\tt print} statement. (A third way is using the
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1961 {\tt write} method of file objects; the standard output file can be
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1962 referenced as {\tt sys.stdout}. See the Library Reference for more
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1963 information on this.)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1964
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1965 Often you'll want more control over the formatting of your output than
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1966 simply printing space-separated values. There are two ways to format
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1967 your output; the first way is to do all the string handling yourself;
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1968 using string slicing and concatenation operations you can create any
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1969 lay-out you can imagine. The standard module {\tt string} contains
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1970 some useful operations for padding strings to a given column width;
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1971 these will be discussed shortly. The second way is to use the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1972 \code{\%} operator with a string as the left argument. \code{\%}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1973 interprets the left argument as a \C\ \code{sprintf()}-style format
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1974 string to be applied to the right argument, and returns the string
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1975 resulting from this formatting operation.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	1976
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1977 One question remains, of course: how do you convert values to strings?
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1978 Luckily, Python has a way to convert any value to a string: pass it to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1979 the \verb/repr()/ function, or just write the value between reverse
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1980 quotes (\verb/``/). Some examples:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	1981
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1982 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1983 >>> x = 10 * 3.14
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1984 >>> y = 200*200
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1985 >>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1986 >>> print s
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1987 The value of x is 31.4, and y is 40000...
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1988 >>> # Reverse quotes work on other types besides numbers:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1989 ... p = [x, y]
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	1990 >>> ps = repr(p)
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1991 >>> ps
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1992 '[31.4, 40000]'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1993 >>> # Converting a string adds string quotes and backslashes:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	1994 ... hello = 'hello, world\n'
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1995 >>> hellos = `hello`
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1996 >>> print hellos
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1997 'hello, world\012'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	1998 >>> # The argument of reverse quotes may be a tuple:
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	1999 ... `x, y, ('spam', 'eggs')`
5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	2000 "(31.4, 40000, ('spam', 'eggs'))"
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2001 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2002 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2003 %
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2004 Here are two ways to write a table of squares and cubes:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2005
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2006 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2007 >>> import string
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2008 >>> for x in range(1, 11):
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2009 ... print string.rjust(`x`, 2), string.rjust(`x*x`, 3),
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2010 ... # Note trailing comma on previous line
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2011 ... print string.rjust(`xxx`, 4)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2012 ...
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2013 1 1 1
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2014 2 4 8
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2015 3 9 27
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2016 4 16 64
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2017 5 25 125
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2018 6 36 216
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2019 7 49 343
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2020 8 64 512
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2021 9 81 729
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2022 10 100 1000
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2023 >>> for x in range(1,11):
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2024 ... print '%2d %3d %4d' % (x, xx, xx*x)
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2025 ...
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2026 1 1 1
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2027 2 4 8
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2028 3 9 27
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2029 4 16 64
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2030 5 25 125
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2031 6 36 216
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2032 7 49 343
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2033 8 64 512
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2034 9 81 729
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2035 10 100 1000
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2036 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2037 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2038 %
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2039 (Note that one space between each column was added by the way {\tt print}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2040 works: it always adds spaces between its arguments.)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2041
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2042 This example demonstrates the function {\tt string.rjust()}, which
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2043 right-justifies a string in a field of a given width by padding it with
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2044 spaces on the left. There are similar functions {\tt string.ljust()}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2045 and {\tt string.center()}. These functions do not write anything, they
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2046 just return a new string. If the input string is too long, they don't
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2047 truncate it, but return it unchanged; this will mess up your column
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2048 lay-out but that's usually better than the alternative, which would be
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2049 lying about a value. (If you really want truncation you can always add
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2050 a slice operation, as in {\tt string.ljust(x,~n)[0:n]}.)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2051
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2052 There is another function, {\tt string.zfill}, which pads a numeric
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2053 string on the left with zeros. It understands about plus and minus
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2054 signs:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2055
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2056 \bcode\begin{verbatim}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2057 >>> string.zfill('12', 5)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2058 '00012'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2059 >>> string.zfill('-3.14', 7)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2060 '-003.14'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2061 >>> string.zfill('3.14159265359', 5)
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2062 '3.14159265359'
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2063 >>>
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2064 \end{verbatim}\ecode
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2065 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2066 Using the \code{\%} operator looks like this:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2067
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2068 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2069 >>> import math
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2070 >>> print 'The value of PI is approximately %5.3f.' % math.pi
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2071 The value of PI is approximately 3.142.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2072 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2073 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2074
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2075 If there is more than one format in the string you pass a tuple as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2076 right operand, e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2077
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2078 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2079 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2080 >>> for name, phone in table.items():
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2081 ... print '%-10s ==> %10d' % (name, phone)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2082 ...
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2083 Jack ==> 4098
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2084 Dcab ==> 8637678
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2085 Sjoerd ==> 4127
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2086 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2087 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2088
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2089 Most formats work exactly as in C and require that you pass the proper
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2090 type; however, if you don't you get an exception, not a core dump.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2091 The \verb\%s\ format is more relaxed: if the corresponding argument is
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2092 not a string object, it is converted to string using the \verb\str()\
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2093 built-in function. Using \verb\*\ to pass the width or precision in
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2094 as a separate (integer) argument is supported. The C formats
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2095 \verb\%n\ and \verb\%p\ are not supported.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2096
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2097 If you have a really long format string that you don't want to split
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2098 up, it would be nice if you could reference the variables to be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2099 formatted by name instead of by position. This can be done by using
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2100 an extension of C formats using the form \verb\%(name)format\, e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2101
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2102 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2103 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2104 >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2105 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2106 >>>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2107 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2108
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2109 This is particularly useful in combination with the new built-in
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2110 \verb\vars()\ function, which returns a dictionary containing all
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2111 local variables.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2112
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2113 \section{Reading and Writing Files}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2114 % Opening files
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2115 \code{open()} returns a file object, and is most commonly used with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2116 two arguments: \code{open(\var{filename},\var{mode})}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2117
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2118 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2119 >>> f=open('/tmp/workfile', 'w')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2120 >>> print f
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2121 <open file '/tmp/workfile', mode 'w' at 80a0960>
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2122 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2123 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2124 The first argument is a string containing the filename. The second
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2125 argument is another string containing a few characters describing the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2126 way in which the file will be used. \var{mode} can be \code{'r'} when
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2127 the file will only be read, \code{'w'} for only writing (an existing
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2128 file with the same name will be erased), and \code{'a'} opens the file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2129 for appending; any data written to the file is automatically added to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2130 the end. \code{'r+'} opens the file for both reading and writing.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2131 The \var{mode} argument is optional; \code{'r'} will be assumed if
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2132 it's omitted.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2133
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2134 On Windows, (XXX does the Mac need this too?) \code{'b'} appended to the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2135 mode opens the file in binary mode, so there are also modes like
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2136 \code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2137 distinction between text and binary files; the end-of-line characters
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2138 in text files are automatically altered slightly when data is read or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2139 written. This behind-the-scenes modification to file data is fine for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2140 ASCII text files, but it'll corrupt binary data like that in JPEGs or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2141 .EXE files. Be very careful to use binary mode when reading and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2142 writing such files.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2143
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2144 \subsection{Methods of file objects}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2145
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2146 The rest of the examples in this section will assume that a file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2147 object called \code{f} has already been created.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2148
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2149 To read a file's contents, call \code{f.read(\var{size})}, which reads
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2150 some quantity of data and returns it as a string. \var{size} is an
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2151 optional numeric argument. When \var{size} is omitted or negative,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2152 the entire contents of the file will be read and returned; it's your
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2153 problem if the file is twice as large as your machine's memory.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2154 Otherwise, at most \var{size} bytes are read and returned. If the end
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2155 of the file has been reached, \code{f.read()} will return an empty
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2156 string (\code {""}).
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2157 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2158 >>> f.read()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2159 'This is the entire file.\012'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2160 >>> f.read()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2161 ''
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2162 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2163 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2164 \code{f.readline()} reads a single line from the file; a newline
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2165 character (\verb/\n/) is left at the end of the string, and is only
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2166 omitted on the last line of the file if the file doesn't end in a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2167 newline. This makes the return value unambiguous; if
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2168 \code{f.readline()} returns an empty string, the end of the file has
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2169 been reached, while a blank line is represented by \verb/'\n'/, a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2170 string containing only a single newline.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2171
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2172 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2173 >>> f.readline()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2174 'This is the first line of the file.\012'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2175 >>> f.readline()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2176 'Second line of the file\012'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2177 >>> f.readline()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2178 ''
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2179 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2180 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2181 \code{f.readlines()} uses {\code{f.readline()} repeatedly, and returns
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2182 a list containing all the lines of data in the file.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2183
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2184 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2185 >>> f.readlines()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2186 ['This is the first line of the file.\012', 'Second line of the file\012']
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2187 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2188 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2189 \code{f.write(\var{string})} writes the contents of \var{string} to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2190 the file, returning \code{None}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2191
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2192 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2193 >>> f.write('This is a test\n')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2194 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2195 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2196 \code{f.tell()} returns an integer giving the file object's current
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2197 position in the file, measured in bytes from the beginning of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2198 file. To change the file object's position, use
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2199 \code{f.seek(\var{offset}, \var{from_what})}. The position is
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2200 computed from adding \var{offset} to a reference point; the reference
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2201 point is selected by the \var{from_what} argument. A \var{from_what}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2202 value of 0 measures from the beginning of the file, 1 uses the current
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2203 file position, and 2 uses the end of the file as the reference point.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2204 \var{from_what}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2205 can be omitted and defaults to 0, using the beginning of the file as the reference point.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2206
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2207 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2208 >>> f=open('/tmp/workfile', 'r+')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2209 >>> f.write('0123456789abcdef')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2210 >>> f.seek(5) # Go to the 5th byte in the file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2211 >>> f.read(1)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2212 '5'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2213 >>> f.seek(-3, 2) # Go to the 3rd byte before the end
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2214 >>> f.read(1)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2215 'd'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2216 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2217 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2218 When you're done with a file, call \code{f.close()} to close it and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2219 free up any system resources taken up by the open file. After calling
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2220 \code{f.close()}, attempts to use the file object will automatically fail.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2221
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2222 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2223 >>> f.close()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2224 >>> f.read()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2225 Traceback (innermost last):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2226 File "<stdin>", line 1, in ?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2227 ValueError: I/O operation on closed file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2228 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2229 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2230 File objects have some additional methods, such as \code{isatty()} and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2231 \code{truncate()} which are less frequently used; consult the Library
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2232 Reference for a complete guide to file objects.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2233
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2234 \subsection{The pickle module}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2235
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2236 Strings can easily be written to and read from a file. Numbers take a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2237 bit more effort, since the \code{read()} method only returns strings,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2238 which will have to be passed to a function like \code{string.atoi()},
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2239 which takes a string like \code{'123'} and returns its numeric value
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2240 123. However, when you want to save more complex data types like
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2241 lists, dictionaries, or class instances, things get a lot more
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2242 complicated.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2243
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2244 Rather than have users be constantly writing and debugging code to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2245 save complicated data types, Python provides a standard module called
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2246 \code{pickle}. code{pickle} is an amazing module that can take almost
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2247 any Python object (even some forms of Python code!), and convert it to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2248 a string representation; this process is called \dfn{pickling}.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2249 Reconstructing the object from the string representation is called
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2250 \dfn{unpickling}. Between pickling and unpickling, the string
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2251 representing the object may have been stored in a file or data, or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2252 sent over a network connection to some distant machine.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2253
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2254 If you have an object \code{x}, and a file object \code{f} that's been
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2255 opened for writing, the simplest way to pickle the object takes only
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2256 one line of code:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2257
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2258 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2259 pickle.dump(x, f)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2260 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2261 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2262 To unpickle the object again, if \code{f} is a file object which has been
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2263 opened for reading:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2264
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2265 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2266 x = pickle.load(f)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2267 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2268 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2269 (There are other variants of this, used when pickling many objects or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2270 when you don't want to write the pickled data to a file; consult the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2271 complete documentation for \code{pickle} in the Library Reference.)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2272
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2273 \code{pickle} is the standard way to make Python objects which can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2274 stored and reused by other programs or by a future invocation of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2275 same program; the technical term for this is a \dfn{persistent}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2276 object. Because \code{pickle} is so widely used, many authors who
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2277 write Python extensions take care to ensure that new data types such
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2278 as matrices, XXX more examples needed XXX, can be properly pickled and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2279 unpickled.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2280
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2281
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2282
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2283 \chapter{Errors and Exceptions}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2284
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2285 Until now error messages haven't been more than mentioned, but if you
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2286 have tried out the examples you have probably seen some. There are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2287 (at least) two distinguishable kinds of errors: {\em syntax\ errors}
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2288 and {\em exceptions}.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2289
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2290 \section{Syntax Errors}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2291
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2292 Syntax errors, also known as parsing errors, are perhaps the most common
271 0bf02e1b7f51 * empty log message * Guido van Rossum <guido@python.org> parents: 221 diff changeset	2293 kind of complaint you get while you are still learning Python:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2294
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2295 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2296 >>> while 1 print 'Hello world'
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2297 File "<stdin>", line 1
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2298 while 1 print 'Hello world'
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2299 ^
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2300 SyntaxError: invalid syntax
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2301 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2302 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2303 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2304 The parser repeats the offending line and displays a little `arrow'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2305 pointing at the earliest point in the line where the error was detected.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2306 The error is caused by (or at least detected at) the token
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2307 {\em preceding}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2308 the arrow: in the example, the error is detected at the keyword
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2309 {\tt print}, since a colon ({\tt :}) is missing before it.
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2310 File name and line number are printed so you know where to look in case
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2311 the input came from a script.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2312
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2313 \section{Exceptions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2314
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2315 Even if a statement or expression is syntactically correct, it may
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2316 cause an error when an attempt is made to execute it.
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2317 Errors detected during execution are called {\em exceptions} and are
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2318 not unconditionally fatal: you will soon learn how to handle them in
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2319 Python programs. Most exceptions are not handled by programs,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2320 however, and result in error messages as shown here:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2321
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2322 \bcode\small\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2323 >>> 10 * (1/0)
1426 c887a1f30525 * lib2.tex (sys): updated sys.std{in,out,err} docs. Added Guido van Rossum <guido@python.org> parents: 1412 diff changeset	2324 Traceback (innermost last):
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2325 File "<stdin>", line 1
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2326 ZeroDivisionError: integer division or modulo
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	2327 >>> 4 + spam*3
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2328 Traceback (innermost last):
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2329 File "<stdin>", line 1
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	2330 NameError: spam
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2331 >>> '2' + 2
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2332 Traceback (innermost last):
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2333 File "<stdin>", line 1
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2334 TypeError: illegal argument type for built-in operation
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2335 >>>
4509 9ca59424020e (tut.tex): Added matching \normalsize after \small font control command Fred Drake <fdrake@acm.org> parents: 4491 diff changeset	2336 \end{verbatim}\normalsize\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2337 %
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2338 The last line of the error message indicates what happened.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2339 Exceptions come in different types, and the type is printed as part of
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2340 the message: the types in the example are
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2341 {\tt ZeroDivisionError},
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2342 {\tt NameError}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2343 and
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2344 {\tt TypeError}.
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2345 The string printed as the exception type is the name of the built-in
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2346 name for the exception that occurred. This is true for all built-in
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2347 exceptions, but need not be true for user-defined exceptions (although
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2348 it is a useful convention).
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2349 Standard exception names are built-in identifiers (not reserved
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2350 keywords).
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2351
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2352 The rest of the line is a detail whose interpretation depends on the
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2353 exception type; its meaning is dependent on the exception type.
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2354
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2355 The preceding part of the error message shows the context where the
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2356 exception happened, in the form of a stack backtrace.
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2357 In general it contains a stack backtrace listing source lines; however,
3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2358 it will not display lines read from standard input.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2359
4452 edab097882d8 Got rid of most XXXes in the News chapter. Bumped the version to 1.4. Guido van Rossum <guido@python.org> parents: 4379 diff changeset	2360 The Python Library Reference Manual lists the built-in exceptions and
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2361 their meanings.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2362
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2363 \section{Handling Exceptions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2364
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2365 It is possible to write programs that handle selected exceptions.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2366 Look at the following example, which prints a table of inverses of
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2367 some floating point numbers:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2368
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2369 \bcode\begin{verbatim}
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2370 >>> numbers = [0.3333, 2.5, 0, 10]
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2371 >>> for x in numbers:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2372 ... print x,
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2373 ... try:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2374 ... print 1.0 / x
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2375 ... except ZeroDivisionError:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2376 ... print '* has no inverse *'
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2377 ...
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2378 0.3333 3.00030003
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2379 2.5 0.4
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2380 0 * has no inverse *
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2381 10 0.1
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2382 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2383 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2384 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2385 The {\tt try} statement works as follows.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2386 \begin{itemize}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2387 \item
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2388 First, the
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2389 {\em try\ clause}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2390 (the statement(s) between the {\tt try} and {\tt except} keywords) is
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2391 executed.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2392 \item
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2393 If no exception occurs, the
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2394 {\em except\ clause}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2395 is skipped and execution of the {\tt try} statement is finished.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2396 \item
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2397 If an exception occurs during execution of the try clause,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2398 the rest of the clause is skipped. Then if
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2399 its type matches the exception named after the {\tt except} keyword,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2400 the rest of the try clause is skipped, the except clause is executed,
f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2401 and then execution continues after the {\tt try} statement.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2402 \item
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2403 If an exception occurs which does not match the exception named in the
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2404 except clause, it is passed on to outer try statements; if no handler is
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2405 found, it is an
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2406 {\em unhandled\ exception}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2407 and execution stops with a message as shown above.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2408 \end{itemize}
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2409 A {\tt try} statement may have more than one except clause, to specify
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2410 handlers for different exceptions.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2411 At most one handler will be executed.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2412 Handlers only handle exceptions that occur in the corresponding try
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2413 clause, not in other handlers of the same {\tt try} statement.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2414 An except clause may name multiple exceptions as a parenthesized list,
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2415 e.g.:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2416
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2417 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2418 ... except (RuntimeError, TypeError, NameError):
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2419 ... pass
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2420 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2421 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2422 The last except clause may omit the exception name(s), to serve as a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2423 wildcard.
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2424 Use this with extreme caution, since it is easy to mask a real
9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2425 programming error in this way!
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2426
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2427 The \verb\try...except\ statement has an optional \verb\else\ clause,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2428 which must follow all \verb\except\ clauses. It is useful to place
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2429 code that must be executed if the \verb\try\ clause does not raise an
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2430 exception. For example:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2431
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2432 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2433 for arg in sys.argv:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2434 try:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2435 f = open(arg, 'r')
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2436 except IOError:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2437 print 'cannot open', arg
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2438 else:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2439 print arg, 'has', len(f.readlines()), 'lines'
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2440 f.close()
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2441 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2442
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2443
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2444 When an exception occurs, it may have an associated value, also known as
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2445 the exceptions's
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2446 {\em argument}.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2447 The presence and type of the argument depend on the exception type.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2448 For exception types which have an argument, the except clause may
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2449 specify a variable after the exception name (or list) to receive the
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2450 argument's value, as follows:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2451
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2452 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2453 >>> try:
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	2454 ... spam()
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2455 ... except NameError, x:
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2456 ... print 'name', x, 'undefined'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2457 ...
2063 5ed065943526 spam -> foo (etc.) in examples Guido van Rossum <guido@python.org> parents: 2013 diff changeset	2458 name spam undefined
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2459 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2460 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2461 %
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2462 If an exception has an argument, it is printed as the last part
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2463 (`detail') of the message for unhandled exceptions.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2464
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2465 Exception handlers don't just handle exceptions if they occur
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2466 immediately in the try clause, but also if they occur inside functions
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2467 that are called (even indirectly) in the try clause.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2468 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2469
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2470 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2471 >>> def this_fails():
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2472 ... x = 1/0
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2473 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2474 >>> try:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2475 ... this_fails()
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2476 ... except ZeroDivisionError, detail:
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2477 ... print 'Handling run-time error:', detail
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2478 ...
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2479 Handling run-time error: integer division or modulo
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2480 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2481 \end{verbatim}\ecode
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2482 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2483
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2484 \section{Raising Exceptions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2485
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2486 The {\tt raise} statement allows the programmer to force a specified
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2487 exception to occur.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2488 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2489
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2490 \bcode\begin{verbatim}
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2491 >>> raise NameError, 'HiThere'
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2492 Traceback (innermost last):
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2493 File "<stdin>", line 1
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2494 NameError: HiThere
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2495 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2496 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2497 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2498 The first argument to {\tt raise} names the exception to be raised.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2499 The optional second argument specifies the exception's argument.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2500
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2501 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2502
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2503 \section{User-defined Exceptions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2504
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2505 Programs may name their own exceptions by assigning a string to a
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2506 variable.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2507 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2508
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2509 \bcode\begin{verbatim}
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2510 >>> my_exc = 'my_exc'
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2511 >>> try:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2512 ... raise my_exc, 2*2
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2513 ... except my_exc, val:
221 edda9aad3e8f Minor improvements. Removed footnote about CWI pathnames. Guido van Rossum <guido@python.org> parents: 149 diff changeset	2514 ... print 'My exception occurred, value:', val
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2515 ...
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2516 My exception occurred, value: 4
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2517 >>> raise my_exc, 1
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2518 Traceback (innermost last):
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2519 File "<stdin>", line 1
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2520 my_exc: 1
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2521 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2522 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2523 %
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2524 Many standard modules use this to report errors that may occur in
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2525 functions they define.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2526
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2527 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2528
342 f3795ac146ce Too much to describe changed... Guido van Rossum <guido@python.org> parents: 283 diff changeset	2529 \section{Defining Clean-up Actions}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2530
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2531 The {\tt try} statement has another optional clause which is intended to
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2532 define clean-up actions that must be executed under all circumstances.
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2533 For example:
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2534
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2535 \bcode\begin{verbatim}
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2536 >>> try:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2537 ... raise KeyboardInterrupt
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2538 ... finally:
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2539 ... print 'Goodbye, world!'
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2540 ...
d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2541 Goodbye, world!
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2542 Traceback (innermost last):
128 3bed76cdac0c Most silly things fixed. Guido van Rossum <guido@python.org> parents: 121 diff changeset	2543 File "<stdin>", line 2
1283 9181da406978 Lots of small changes collected over months... Guido van Rossum <guido@python.org> parents: 1100 diff changeset	2544 KeyboardInterrupt
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2545 >>>
132 65edde022d71 Changed code environment into \bcode and \ecode macros. Guido van Rossum <guido@python.org> parents: 128 diff changeset	2546 \end{verbatim}\ecode
563 73e266bf7ac6 Cosmetic changes; added more subsections to chapter 2; new syntax (==). Guido van Rossum <guido@python.org> parents: 452 diff changeset	2547 %
933 c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2548 A {\tt finally} clause is executed whether or not an exception has
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2549 occurred in the {\tt try} clause. When an exception has occurred, it
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2550 is re-raised after the {\tt finally} clause is executed. The
933 c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2551 {\tt finally} clause is also executed ``on the way out'' when the
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2552 {\tt try} statement is left via a {\tt break} or {\tt return}
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2553 statement.
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2554
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2555 A {\tt try} statement must either have one or more {\tt except}
c432738cf69a Fixed descr of try/finally Guido van Rossum <guido@python.org> parents: 929 diff changeset	2556 clauses or one {\tt finally} clause, but not both.
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	2557
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2558 \chapter{Classes}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2559
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2560 Python's class mechanism adds classes to the language with a minimum
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2561 of new syntax and semantics. It is a mixture of the class mechanisms
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2562 found in \Cpp{} and Modula-3. As is true for modules, classes in Python
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2563 do not put an absolute barrier between definition and user, but rather
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2564 rely on the politeness of the user not to ``break into the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2565 definition.'' The most important features of classes are retained
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2566 with full power, however: the class inheritance mechanism allows
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2567 multiple base classes, a derived class can override any methods of its
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2568 base class(es), a method can call the method of a base class with the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2569 same name. Objects can contain an arbitrary amount of private data.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2570
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2571 In \Cpp{} terminology, all class members (including the data members) are
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2572 {\em public}, and all member functions are {\em virtual}. There are
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2573 no special constructors or destructors. As in Modula-3, there are no
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2574 shorthands for referencing the object's members from its methods: the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2575 method function is declared with an explicit first argument
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2576 representing the object, which is provided implicitly by the call. As
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2577 in Smalltalk, classes themselves are objects, albeit in the wider
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2578 sense of the word: in Python, all data types are objects. This
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2579 provides semantics for importing and renaming. But, just like in \Cpp{}
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2580 or Modula-3, built-in types cannot be used as base classes for
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2581 extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2582 built-in operators with special syntax (arithmetic operators,
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2583 subscripting etc.) can be redefined for class members.
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2584
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2585 \section{A word about terminology}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2586
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2587 Lacking universally accepted terminology to talk about classes, I'll
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2588 make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2589 terms, since its object-oriented semantics are closer to those of
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2590 Python than \Cpp{}, but I expect that few readers have heard of it...)
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2591
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2592 I also have to warn you that there's a terminological pitfall for
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2593 object-oriented readers: the word ``object'' in Python does not
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2594 necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2595 Smalltalk, not all types in Python are classes: the basic built-in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2596 types like integers and lists aren't, and even somewhat more exotic
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2597 types like files aren't. However, {\em all} Python types share a little
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2598 bit of common semantics that is best described by using the word
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2599 object.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2600
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2601 Objects have individuality, and multiple names (in multiple scopes)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2602 can be bound to the same object. This is known as aliasing in other
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2603 languages. This is usually not appreciated on a first glance at
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2604 Python, and can be safely ignored when dealing with immutable basic
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2605 types (numbers, strings, tuples). However, aliasing has an
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2606 (intended!) effect on the semantics of Python code involving mutable
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2607 objects such as lists, dictionaries, and most types representing
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2608 entities outside the program (files, windows, etc.). This is usually
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2609 used to the benefit of the program, since aliases behave like pointers
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2610 in some respects. For example, passing an object is cheap since only
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2611 a pointer is passed by the implementation; and if a function modifies
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2612 an object passed as an argument, the caller will see the change --- this
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2613 obviates the need for two different argument passing mechanisms as in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2614 Pascal.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2615
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2616
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2617 \section{Python scopes and name spaces}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2618
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2619 Before introducing classes, I first have to tell you something about
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2620 Python's scope rules. Class definitions play some neat tricks with
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2621 name spaces, and you need to know how scopes and name spaces work to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2622 fully understand what's going on. Incidentally, knowledge about this
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2623 subject is useful for any advanced Python programmer.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2624
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2625 Let's begin with some definitions.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2626
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2627 A {\em name space} is a mapping from names to objects. Most name
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2628 spaces are currently implemented as Python dictionaries, but that's
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2629 normally not noticeable in any way (except for performance), and it
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2630 may change in the future. Examples of name spaces are: the set of
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2631 built-in names (functions such as \verb\abs()\, and built-in exception
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2632 names); the global names in a module; and the local names in a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2633 function invocation. In a sense the set of attributes of an object
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1852 diff changeset	2634 also form a name space. The important thing to know about name
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2635 spaces is that there is absolutely no relation between names in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2636 different name spaces; for instance, two different modules may both
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2637 define a function ``maximize'' without confusion --- users of the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2638 modules must prefix it with the module name.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2639
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2640 By the way, I use the word {\em attribute} for any name following a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2641 dot --- for example, in the expression \verb\z.real\, \verb\real\ is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2642 an attribute of the object \verb\z\. Strictly speaking, references to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2643 names in modules are attribute references: in the expression
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2644 \verb\modname.funcname\, \verb\modname\ is a module object and
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2645 \verb\funcname\ is an attribute of it. In this case there happens to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2646 be a straightforward mapping between the module's attributes and the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2647 global names defined in the module: they share the same name space!%
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2648 \footnote{
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2649 Except for one thing. Module objects have a secret read-only
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2650 attribute called {\tt __dict__} which returns the dictionary
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2651 used to implement the module's name space; the name
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2652 {\tt __dict__} is an attribute but not a global name.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2653 Obviously, using this violates the abstraction of name space
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2654 implementation, and should be restricted to things like
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2655 post-mortem debuggers...
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2656 }
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2657
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2658 Attributes may be read-only or writable. In the latter case,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2659 assignment to attributes is possible. Module attributes are writable:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2660 you can write \verb\modname.the_answer = 42\. Writable attributes may
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2661 also be deleted with the del statement, e.g.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2662 \verb\del modname.the_answer\.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2663
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2664 Name spaces are created at different moments and have different
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2665 lifetimes. The name space containing the built-in names is created
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2666 when the Python interpreter starts up, and is never deleted. The
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2667 global name space for a module is created when the module definition
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2668 is read in; normally, module name spaces also last until the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2669 interpreter quits. The statements executed by the top-level
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2670 invocation of the interpreter, either read from a script file or
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2671 interactively, are considered part of a module called \verb\__main__\,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2672 so they have their own global name space. (The built-in names
1374 89d7d5e136ad * lib3.tex (module string): added rindex(). Guido van Rossum <guido@python.org> parents: 1283 diff changeset	2673 actually also live in a module; this is called \verb\__builtin__\.)
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2674
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2675 The local name space for a function is created when the function is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2676 called, and deleted when the function returns or raises an exception
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2677 that is not handled within the function. (Actually, forgetting would
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2678 be a better way to describe what actually happens.) Of course,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2679 recursive invocations each have their own local name space.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2680
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2681 A {\em scope} is a textual region of a Python program where a name space
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2682 is directly accessible. ``Directly accessible'' here means that an
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2683 unqualified reference to a name attempts to find the name in the name
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2684 space.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2685
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2686 Although scopes are determined statically, they are used dynamically.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2687 At any time during execution, exactly three nested scopes are in use
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2688 (i.e., exactly three name spaces are directly accessible): the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2689 innermost scope, which is searched first, contains the local names,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2690 the middle scope, searched next, contains the current module's global
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2691 names, and the outermost scope (searched last) is the name space
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2692 containing built-in names.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2693
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2694 Usually, the local scope references the local names of the (textually)
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2553 diff changeset	2695 current function. Outside of functions, the local scope references
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2696 the same name space as the global scope: the module's name space.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2697 Class definitions place yet another name space in the local scope.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2698
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2699 It is important to realize that scopes are determined textually: the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2700 global scope of a function defined in a module is that module's name
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2701 space, no matter from where or by what alias the function is called.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2702 On the other hand, the actual search for names is done dynamically, at
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2553 diff changeset	2703 run time --- however, the language definition is evolving towards
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2704 static name resolution, at ``compile'' time, so don't rely on dynamic
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2705 name resolution! (In fact, local variables are already determined
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2706 statically.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2707
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2708 A special quirk of Python is that assignments always go into the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2709 innermost scope. Assignments do not copy data --- they just
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2710 bind names to objects. The same is true for deletions: the statement
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2711 \verb\del x\ removes the binding of x from the name space referenced by the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2712 local scope. In fact, all operations that introduce new names use the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2713 local scope: in particular, import statements and function definitions
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2714 bind the module or function name in the local scope. (The
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2715 \verb\global\ statement can be used to indicate that particular
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2716 variables live in the global scope.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2717
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2718
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2719 \section{A first look at classes}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2720
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2721 Classes introduce a little bit of new syntax, three new object types,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2722 and some new semantics.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2723
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2724
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2725 \subsection{Class definition syntax}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2726
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2727 The simplest form of class definition looks like this:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2728
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2729 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2730 class ClassName:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2731 <statement-1>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2732 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2733 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2734 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2735 <statement-N>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2736 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2737
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2738 Class definitions, like function definitions (\verb\def\ statements)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2739 must be executed before they have any effect. (You could conceivably
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2740 place a class definition in a branch of an \verb\if\ statement, or
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2741 inside a function.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2742
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2743 In practice, the statements inside a class definition will usually be
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2744 function definitions, but other statements are allowed, and sometimes
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2745 useful --- we'll come back to this later. The function definitions
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2746 inside a class normally have a peculiar form of argument list,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2747 dictated by the calling conventions for methods --- again, this is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2748 explained later.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2749
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2750 When a class definition is entered, a new name space is created, and
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2751 used as the local scope --- thus, all assignments to local variables
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2752 go into this new name space. In particular, function definitions bind
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2753 the name of the new function here.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2754
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2755 When a class definition is left normally (via the end), a {\em class
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2756 object} is created. This is basically a wrapper around the contents
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2757 of the name space created by the class definition; we'll learn more
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2758 about class objects in the next section. The original local scope
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2759 (the one in effect just before the class definitions was entered) is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2760 reinstated, and the class object is bound here to class name given in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2761 the class definition header (ClassName in the example).
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2762
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2763
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2764 \subsection{Class objects}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2765
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2766 Class objects support two kinds of operations: attribute references
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2767 and instantiation.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2768
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2769 {\em Attribute references} use the standard syntax used for all
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2770 attribute references in Python: \verb\obj.name\. Valid attribute
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2771 names are all the names that were in the class's name space when the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2772 class object was created. So, if the class definition looked like
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2773 this:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2774
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2775 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2776 class MyClass:
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2777 "A simple example class"
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2778 i = 12345
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2779 def f(x):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2780 return 'hello world'
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2781 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2782
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2783 then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2784 references, returning an integer and a function object, respectively.
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2785 Class attributes can also be assigned to, so you can change the value
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2786 of \verb\MyClass.i\ by assignment. \verb\__doc__\ is also a valid
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2787 attribute that's read-only, returning the docstring belonging to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	2788 the class: \verb\"A simple example class"\).
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2789
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2790 Class {\em instantiation} uses function notation. Just pretend that
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2791 the class object is a parameterless function that returns a new
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2792 instance of the class. For example, (assuming the above class):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2793
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2794 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2795 x = MyClass()
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2796 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2797
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2798 creates a new {\em instance} of the class and assigns this object to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2799 the local variable \verb\x\.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2800
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2801
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2802 \subsection{Instance objects}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2803
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2804 Now what can we do with instance objects? The only operations
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2805 understood by instance objects are attribute references. There are
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2806 two kinds of valid attribute names.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2807
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2808 The first I'll call {\em data attributes}. These correspond to
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	2809 ``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}.
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2810 Data attributes need not be declared; like local variables, they
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2811 spring into existence when they are first assigned to. For example,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2812 if \verb\x\ in the instance of \verb\MyClass\ created above, the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2813 following piece of code will print the value 16, without leaving a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2814 trace:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2815
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2816 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2817 x.counter = 1
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2818 while x.counter < 10:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2819 x.counter = x.counter * 2
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2820 print x.counter
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2821 del x.counter
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2822 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2823
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2824 The second kind of attribute references understood by instance objects
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2825 are {\em methods}. A method is a function that ``belongs to'' an
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2826 object. (In Python, the term method is not unique to class instances:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2827 other object types can have methods as well, e.g., list objects have
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2828 methods called append, insert, remove, sort, and so on. However,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2829 below, we'll use the term method exclusively to mean methods of class
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2830 instance objects, unless explicitly stated otherwise.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2831
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2832 Valid method names of an instance object depend on its class. By
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2833 definition, all attributes of a class that are (user-defined) function
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2834 objects define corresponding methods of its instances. So in our
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2835 example, \verb\x.f\ is a valid method reference, since
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2836 \verb\MyClass.f\ is a function, but \verb\x.i\ is not, since
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2837 \verb\MyClass.i\ is not. But \verb\x.f\ is not the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2838 same thing as \verb\MyClass.f\ --- it is a {\em method object}, not a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2839 function object.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2840
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2841
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2842 \subsection{Method objects}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2843
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2844 Usually, a method is called immediately, e.g.:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2845
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2846 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2847 x.f()
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2848 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2849
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2850 In our example, this will return the string \verb\'hello world'\.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2851 However, it is not necessary to call a method right away: \verb\x.f\
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2852 is a method object, and can be stored away and called at a later
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2853 moment, for example:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2854
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2855 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2856 xf = x.f
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2857 while 1:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2858 print xf()
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2859 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2860
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2861 will continue to print \verb\hello world\ until the end of time.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2862
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2863 What exactly happens when a method is called? You may have noticed
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2864 that \verb\x.f()\ was called without an argument above, even though
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2865 the function definition for \verb\f\ specified an argument. What
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2866 happened to the argument? Surely Python raises an exception when a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2867 function that requires an argument is called without any --- even if
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2868 the argument isn't actually used...
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2869
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2870 Actually, you may have guessed the answer: the special thing about
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2871 methods is that the object is passed as the first argument of the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2872 function. In our example, the call \verb\x.f()\ is exactly equivalent
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2873 to \verb\MyClass.f(x)\. In general, calling a method with a list of
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2874 {\em n} arguments is equivalent to calling the corresponding function
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2875 with an argument list that is created by inserting the method's object
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2876 before the first argument.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2877
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2878 If you still don't understand how methods work, a look at the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2879 implementation can perhaps clarify matters. When an instance
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2880 attribute is referenced that isn't a data attribute, its class is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2881 searched. If the name denotes a valid class attribute that is a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2882 function object, a method object is created by packing (pointers to)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2883 the instance object and the function object just found together in an
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2884 abstract object: this is the method object. When the method object is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2885 called with an argument list, it is unpacked again, a new argument
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2886 list is constructed from the instance object and the original argument
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2887 list, and the function object is called with this new argument list.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2888
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2889
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2890 \section{Random remarks}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2891
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2892
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2893 [These should perhaps be placed more carefully...]
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2894
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2895
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2896 Data attributes override method attributes with the same name; to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2897 avoid accidental name conflicts, which may cause hard-to-find bugs in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2898 large programs, it is wise to use some kind of convention that
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2899 minimizes the chance of conflicts, e.g., capitalize method names,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2900 prefix data attribute names with a small unique string (perhaps just
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2901 an underscore), or use verbs for methods and nouns for data attributes.
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2902
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2903
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2904 Data attributes may be referenced by methods as well as by ordinary
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2905 users (``clients'') of an object. In other words, classes are not
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2906 usable to implement pure abstract data types. In fact, nothing in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2907 Python makes it possible to enforce data hiding --- it is all based
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2908 upon convention. (On the other hand, the Python implementation,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2909 written in C, can completely hide implementation details and control
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2910 access to an object if necessary; this can be used by extensions to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2911 Python written in C.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2912
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2913
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2914 Clients should use data attributes with care --- clients may mess up
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2915 invariants maintained by the methods by stamping on their data
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2916 attributes. Note that clients may add data attributes of their own to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2917 an instance object without affecting the validity of the methods, as
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2918 long as name conflicts are avoided --- again, a naming convention can
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2919 save a lot of headaches here.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2920
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2921
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2922 There is no shorthand for referencing data attributes (or other
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2923 methods!) from within methods. I find that this actually increases
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2924 the readability of methods: there is no chance of confusing local
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2925 variables and instance variables when glancing through a method.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2926
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2927
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2928 Conventionally, the first argument of methods is often called
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2929 \verb\self\. This is nothing more than a convention: the name
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2930 \verb\self\ has absolutely no special meaning to Python. (Note,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2931 however, that by not following the convention your code may be less
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2932 readable by other Python programmers, and it is also conceivable that
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2933 a {\em class browser} program be written which relies upon such a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2934 convention.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2935
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2936
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2937 Any function object that is a class attribute defines a method for
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2938 instances of that class. It is not necessary that the function
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2939 definition is textually enclosed in the class definition: assigning a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2940 function object to a local variable in the class is also ok. For
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2941 example:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2942
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2943 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2944 # Function defined outside the class
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2945 def f1(self, x, y):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2946 return min(x, x+y)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2947
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2948 class C:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2949 f = f1
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2950 def g(self):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2951 return 'hello world'
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2952 h = g
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2953 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2954
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2955 Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2956 \verb\C\ that refer to function objects, and consequently they are all
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2957 methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2958 to \verb\g\. Note that this practice usually only serves to confuse
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2959 the reader of a program.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2960
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2961
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2962 Methods may call other methods by using method attributes of the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2963 \verb\self\ argument, e.g.:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2964
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2965 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2966 class Bag:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2967 def empty(self):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2968 self.data = []
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2969 def add(self, x):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2970 self.data.append(x)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2971 def addtwice(self, x):
952 7d8e51e580d1 Fixed botched lay-out in class example Guido van Rossum <guido@python.org> parents: 933 diff changeset	2972 self.add(x)
7d8e51e580d1 Fixed botched lay-out in class example Guido van Rossum <guido@python.org> parents: 933 diff changeset	2973 self.add(x)
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2974 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2975
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2976
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2977 The instantiation operation (``calling'' a class object) creates an
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	2978 empty object. Many classes like to create objects in a known initial
1935 d9a3e30b2e47 Removed description of class.init() method. Guido van Rossum <guido@python.org> parents: 1934 diff changeset	2979 state. Therefore a class may define a special method named
d9a3e30b2e47 Removed description of class.init() method. Guido van Rossum <guido@python.org> parents: 1934 diff changeset	2980 \verb\__init__\, like this:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2981
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2982 \begin{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2983 def __init__(self):
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2984 self.empty()
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2985 \end{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2986
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2987 When a class defines an \verb\__init__\ method, class instantiation
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2988 automatically invokes \verb\__init__\ for the newly-created class
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2989 instance. So in the \verb\Bag\ example, a new and initialized instance
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2990 can be obtained by:
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2991
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2992 \begin{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2993 x = Bag()
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2994 \end{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2995
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2996 Of course, the \verb\__init__\ method may have arguments for greater
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2997 flexibility. In that case, arguments given to the class instantiation
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2998 operator are passed on to \verb\__init__\. For example,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	2999
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3000 \bcode\begin{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3001 >>> class Complex:
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3002 ... def __init__(self, realpart, imagpart):
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3003 ... self.r = realpart
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3004 ... self.i = imagpart
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3005 ...
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3006 >>> x = Complex(3.0,-4.5)
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3007 >>> x.r, x.i
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3008 (3.0, -4.5)
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3009 >>>
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3010 \end{verbatim}\ecode
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3011 %
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3012 Methods may reference global names in the same way as ordinary
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3013 functions. The global scope associated with a method is the module
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3014 containing the class definition. (The class itself is never used as a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3015 global scope!) While one rarely encounters a good reason for using
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3016 global data in a method, there are many legitimate uses of the global
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3017 scope: for one thing, functions and modules imported into the global
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3018 scope can be used by methods, as well as functions and classes defined
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3019 in it. Usually, the class containing the method is itself defined in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3020 this global scope, and in the next section we'll find some good
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3021 reasons why a method would want to reference its own class!
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3022
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3023
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3024 \section{Inheritance}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3025
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3026 Of course, a language feature would not be worthy of the name ``class''
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3027 without supporting inheritance. The syntax for a derived class
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3028 definition looks as follows:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3029
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3030 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3031 class DerivedClassName(BaseClassName):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3032 <statement-1>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3033 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3034 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3035 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3036 <statement-N>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3037 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3038
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3039 The name \verb\BaseClassName\ must be defined in a scope containing
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3040 the derived class definition. Instead of a base class name, an
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3041 expression is also allowed. This is useful when the base class is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3042 defined in another module, e.g.,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3043
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3044 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3045 class DerivedClassName(modname.BaseClassName):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3046 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3047
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3048 Execution of a derived class definition proceeds the same as for a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3049 base class. When the class object is constructed, the base class is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3050 remembered. This is used for resolving attribute references: if a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3051 requested attribute is not found in the class, it is searched in the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3052 base class. This rule is applied recursively if the base class itself
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3053 is derived from some other class.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3054
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3055 There's nothing special about instantiation of derived classes:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3056 \verb\DerivedClassName()\ creates a new instance of the class. Method
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3057 references are resolved as follows: the corresponding class attribute
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3058 is searched, descending down the chain of base classes if necessary,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3059 and the method reference is valid if this yields a function object.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3060
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3061 Derived classes may override methods of their base classes. Because
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3062 methods have no special privileges when calling other methods of the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3063 same object, a method of a base class that calls another method
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3064 defined in the same base class, may in fact end up calling a method of
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	3065 a derived class that overrides it. (For \Cpp{} programmers: all methods
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3066 in Python are ``virtual functions''.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3067
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3068 An overriding method in a derived class may in fact want to extend
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3069 rather than simply replace the base class method of the same name.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3070 There is a simple way to call the base class method directly: just
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3071 call \verb\BaseClassName.methodname(self, arguments)\. This is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3072 occasionally useful to clients as well. (Note that this only works if
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3073 the base class is defined or imported directly in the global scope.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3074
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3075
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3076 \subsection{Multiple inheritance}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3077
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1426 diff changeset	3078 Python supports a limited form of multiple inheritance as well. A
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3079 class definition with multiple base classes looks as follows:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3080
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3081 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3082 class DerivedClassName(Base1, Base2, Base3):
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3083 <statement-1>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3084 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3085 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3086 .
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3087 <statement-N>
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3088 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3089
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3090 The only rule necessary to explain the semantics is the resolution
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3091 rule used for class attribute references. This is depth-first,
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3092 left-to-right. Thus, if an attribute is not found in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3093 \verb\DerivedClassName\, it is searched in \verb\Base1\, then
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3094 (recursively) in the base classes of \verb\Base1\, and only if it is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3095 not found there, it is searched in \verb\Base2\, and so on.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3096
1100 ff1899dcda05 Incorporated Jan-Hein's changes and texinfo conversion. Guido van Rossum <guido@python.org> parents: 1040 diff changeset	3097 (To some people breadth first---searching \verb\Base2\ and
ff1899dcda05 Incorporated Jan-Hein's changes and texinfo conversion. Guido van Rossum <guido@python.org> parents: 1040 diff changeset	3098 \verb\Base3\ before the base classes of \verb\Base1\---looks more
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3099 natural. However, this would require you to know whether a particular
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3100 attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3101 one of its base classes before you can figure out the consequences of
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3102 a name conflict with an attribute of \verb\Base2\. The depth-first
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3103 rule makes no differences between direct and inherited attributes of
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3104 \verb\Base1\.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3105
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3106 It is clear that indiscriminate use of multiple inheritance is a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3107 maintenance nightmare, given the reliance in Python on conventions to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3108 avoid accidental name conflicts. A well-known problem with multiple
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3109 inheritance is a class derived from two classes that happen to have a
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3110 common base class. While it is easy enough to figure out what happens
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3111 in this case (the instance will have a single copy of ``instance
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3112 variables'' or data attributes used by the common base class), it is
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3113 not clear that these semantics are in any way useful.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3114
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3115
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3116 \section{Private variables through name mangling}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3117
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3118 There is now limited support for class-private
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3119 identifiers. Any identifier of the form \code{__spam} (at least two
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3120 leading underscores, at most one trailing underscore) is now textually
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3121 replaced with \code{_classname__spam}, where \code{classname} is the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3122 current class name with leading underscore(s) stripped. This mangling
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3123 is done without regard of the syntactic position of the identifier, so
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3124 it can be used to define class-private instance and class variables,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3125 methods, as well as globals, and even to store instance variables
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3126 private to this class on instances of {\em other} classes. Truncation
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3127 may occur when the mangled name would be longer than 255 characters.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3128 Outside classes, or when the class name consists of only underscores,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3129 no mangling occurs.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3130
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3131 Name mangling is intended to give classes an easy way to define
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3132 ``private'' instance variables and methods, without having to worry
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3133 about instance variables defined by derived classes, or mucking with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3134 instance variables by code outside the class. Note that the mangling
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3135 rules are designed mostly to avoid accidents; it still is possible for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3136 a determined soul to access or modify a variable that is considered
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3137 private. This can even be useful, e.g. for the debugger, and that's
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3138 one reason why this loophole is not closed. (Buglet: derivation of a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3139 class with the same name as the base class makes use of private
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3140 variables of the base class possible.)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3141
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3142 Notice that code passed to \code{exec}, \code{eval()} or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3143 \code{evalfile()} does not consider the classname of the invoking
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3144 class to be the current class; this is similar to the effect of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3145 \code{global} statement, the effect of which is likewise restricted to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3146 code that is byte-compiled together. The same restriction applies to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3147 \code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3148 when referencing \code{__dict__} directly.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3149
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3150 Here's an example of a class that implements its own
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3151 \code{__getattr__} and \code{__setattr__} methods and stores all
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3152 attributes in a private variable, in a way that works in Python 1.4 as
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3153 well as in previous versions:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3154
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3155 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3156 class VirtualAttributes:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3157 __vdict = None
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3158 __vdict_name = locals().keys()[0]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3159
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3160 def __init__(self):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3161 self.__dict__[self.__vdict_name] = {}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3162
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3163 def __getattr__(self, name):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3164 return self.__vdict[name]
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3165
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3166 def __setattr__(self, name, value):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3167 self.__vdict[name] = value
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3168 \end{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3169
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3170 %{\em Warning: this is an experimental feature.} To avoid all
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3171 %potential problems, refrain from using identifiers starting with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3172 %double underscore except for predefined uses like \code{__init__}. To
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3173 %use private names while maintaining future compatibility: refrain from
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3174 %using the same private name in classes related via subclassing; avoid
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3175 %explicit (manual) mangling/unmangling; and assume that at some point
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3176 %in the future, leading double underscore will revert to being just a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3177 %naming convention. Discussion on extensive compile-time declarations
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3178 %are currently underway, and it is impossible to predict what solution
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3179 %will eventually be chosen for private names. Double leading
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3180 %underscore is still a candidate, of course --- just not the only one.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3181 %It is placed in the distribution in the belief that it is useful, and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3182 %so that widespread experience with its use can be gained. It will not
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3183 %be removed without providing a better solution and a migration path.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3184
929 ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3185 \section{Odds and ends}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3186
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3187 Sometimes it is useful to have a data type similar to the Pascal
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3188 ``record'' or C ``struct'', bundling together a couple of named data
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3189 items. An empty class definition will do nicely, e.g.:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3190
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3191 \begin{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3192 class Employee:
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3193 pass
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3194
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3195 john = Employee() # Create an empty employee record
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3196
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3197 # Fill the fields of the record
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3198 john.name = 'John Doe'
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3199 john.dept = 'computer lab'
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3200 john.salary = 1000
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3201 \end{verbatim}
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3202
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3203
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3204 A piece of Python code that expects a particular abstract data type
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3205 can often be passed a class that emulates the methods of that data
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3206 type instead. For instance, if you have a function that formats some
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3207 data from a file object, you can define a class with methods
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3208 \verb\read()\ and \verb\readline()\ that gets the data from a string
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3209 buffer instead, and pass it as an argument. (Unfortunately, this
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3210 technique has its limitations: a class can't define operations that
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3211 are accessed by special syntax such as sequence subscripting or
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3212 arithmetic operators, and assigning such a ``pseudo-file'' to
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3213 \verb\sys.stdin\ will not cause the interpreter to read further input
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3214 from it.)
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3215
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3216
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3217 Instance method objects have attributes, too: \verb\m.im_self\ is the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3218 object of which the method is an instance, and \verb\m.im_func\ is the
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3219 function object corresponding to the method.
ff02b948c9a8 Add chapter on classes (mostly from ../misc/CLASSES). Guido van Rossum <guido@python.org> parents: 808 diff changeset	3220
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3221 \subsection{Exceptions Can Be Classes}
2344 279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3222
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3223 User-defined exceptions are no longer limited to being string objects
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3224 --- they can be identified by classes as well. Using this mechanism it
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3225 is possible to create extensible hierarchies of exceptions.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3226
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3227 There are two new valid (semantic) forms for the raise statement:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3228
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3229 \begin{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3230 raise Class, instance
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3231
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3232 raise instance
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3233 \end{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3234
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3235 In the first form, \code{instance} must be an instance of \code{Class}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3236 or of a class derived from it. The second form is a shorthand for
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3237
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3238 \begin{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3239 raise instance.__class__, instance
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3240 \end{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3241
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3242 An except clause may list classes as well as string objects. A class
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3243 in an except clause is compatible with an exception if it is the same
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3244 class or a base class thereof (but not the other way around --- an
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3245 except clause listing a derived class is not compatible with a base
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3246 class). For example, the following code will print B, C, D in that
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3247 order:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3248
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3249 \begin{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3250 class B:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3251 pass
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3252 class C(B):
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3253 pass
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3254 class D(C):
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3255 pass
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3256
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3257 for c in [B, C, D]:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3258 try:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3259 raise c()
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3260 except D:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3261 print "D"
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3262 except C:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3263 print "C"
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3264 except B:
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3265 print "B"
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3266 \end{verbatim}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3267
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3268 Note that if the except clauses were reversed (with ``\code{except B}''
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3269 first), it would have printed B, B, B --- the first matching except
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3270 clause is triggered.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3271
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3272 When an error message is printed for an unhandled exception which is a
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3273 class, the class name is printed, then a colon and a space, and
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3274 finally the instance converted to a string using the built-in function
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3275 \code{str()}.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3276
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3277 In this release, the built-in exceptions are still strings.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3278
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3279 \chapter{What Now?}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3280
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3281 Hopefully reading this tutorial has reinforced your interest in using
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3282 Python. Now what should you do?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3283
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3284 You should read, or at least page through, the Library Reference,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3285 which gives complete (though terse) reference material about types,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3286 functions, and modules that can save you a lot of time when writing
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3287 Python programs. The standard Python distribution includes a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3288 \emph{lot} of code in both C and Python; there are modules to read
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3289 Unix mailboxes, retrieve documents via HTTP, generate random numbers,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3290 parse command-line options, write CGI programs, compress data, and a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3291 lot more; skimming through the Library Reference will give you an idea
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3292 of what's available.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3293
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3294 The major Python Web site is \code{http://www.python.org}; it contains
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3295 code, documentation, and pointers to Python-related pages around the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3296 Web. \code{www.python.org} is mirrored in various places around the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3297 world, such as Europe, Japan, and Australia; a mirror may be faster
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3298 than the main site, depending on your geographical location. A more
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3299 informal site is \code{http://starship.skyport.net}, which contains a
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3300 bunch of Python-related personal home pages; many people have
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3301 downloadable software here.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3302
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3303 For Python-related questions and problem reports, you can post to the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3304 newsgroup \code{comp.lang.python}, or send them to the mailing list at
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3305 \code{python-list@cwi.nl}. The newsgroup and mailing list are
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3306 gatewayed, so messages posted to one will automatically be forwarded
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3307 to the other. There are around 20--30 postings a day, asking (and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3308 answering) questions, suggesting new features, and announcing new
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3309 modules. But before posting, be sure to check the list of Frequently
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3310 Asked Questions (also called the FAQ), at
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3311 \code{http://www.python.org/doc/FAQ.html}, or look for it in the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3312 \code{Misc/} directory of the Python source distribution. The FAQ
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3313 answers many of the questions that come up again and again, and may
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3314 already contain the solution for your problem.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3315
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3316 You can support the Python community by joining the Python Software
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3317 Activity, which runs the python.org web, ftp and email servers, and
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3318 organizes Python workshops. See \code{http://www.python.org/psa/} for
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3319 information on how to join.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3320
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3321
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3322 \chapter{Recent Additions as of Release 1.1}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3323
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3324 XXX Should the stuff in this chapter be deleted, or can a home be found or it elsewhere in the Tutorial?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3325
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3326 \section{Lambda Forms}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3327
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3328 XXX Where to put this? Or just leave it out?
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3329
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3330 By popular demand, a few features commonly found in functional
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3331 programming languages and Lisp have been added to Python. With the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3332 \verb\lambda\ keyword, small anonymous functions can be created.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3333 Here's a function that returns the sum of its two arguments:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3334 \verb\lambda a, b: a+b\. Lambda forms can be used wherever function
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3335 objects are required. They are syntactically restricted to a single
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3336 expression. Semantically, they are just syntactic sugar for a normal
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3337 function definition. Like nested function definitions, lambda forms
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3338 cannot reference variables from the containing scope, but this can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3339 overcome through the judicious use of default argument values, e.g.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3340
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3341 \begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3342 def make_incrementor(n):
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3343 return lambda x, incr=n: x+incr
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3344 \end{verbatim}
2344 279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3345
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3346 \section{Documentation Strings}
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3347
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3348 XXX Where to put this? Or just leave it out?
2344 279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3349
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3350 There are emerging conventions about the content and formatting of
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3351 documentation strings.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3352
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3353 The first line should always be a short, concise summary of the
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3354 object's purpose. For brevity, it should not explicitly state the
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3355 object's name or type, since these are available by other means
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3356 (except if the name happens to be a verb describing a function's
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3357 operation). This line should begin with a capital letter and end with
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3358 a period.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3359
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3360 If there are more lines in the documentation string, the second line
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3361 should be blank, visually separating the summary from the rest of the
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3362 description. The following lines should be one of more of paragraphs
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3363 describing the objects calling conventions, its side effects, etc.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3364
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3365 Some people like to copy the Emacs convention of using UPPER CASE for
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3366 function parameters --- this often saves a few words or lines.
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3367
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3368 The Python parser does not strip indentation from multi-line string
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3369 literals in Python, so tools that process documentation have to strip
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3370 indentation. This is done using the following convention. The first
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3371 non-blank line {\em after} the first line of the string determines the
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3372 amount of indentation for the entire documentation string. (We can't
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3373 use the first line since it is generally adjacent to the string's
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3374 opening quotes so its indentation is not apparent in the string
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3375 literal.) Whitespace ``equivalent'' to this indentation is then
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3376 stripped from the start of all lines of the string. Lines that are
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3377 indented less should not occur, but if they occur all their leading
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3378 whitespace should be stripped. Equivalence of whitespace should be
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3379 tested after expansion of tabs (to 8 spaces, normally).
279d51a18ae4 added chapter on new things in 1.2 Guido van Rossum <guido@python.org> parents: 2063 diff changeset	3380
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3381
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3382 \appendix\chapter{Interactive Input Editing and History Substitution}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3383
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3384 Some versions of the Python interpreter support editing of the current
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3385 input line and history substitution, similar to facilities found in
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3386 the Korn shell and the GNU Bash shell. This is implemented using the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3387 {\em GNU\ Readline} library, which supports Emacs-style and vi-style
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3388 editing. This library has its own documentation which I won't
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3389 duplicate here; however, the basics are easily explained.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3390
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3391 \subsection{Line Editing}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3392
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3393 If supported, input line editing is active whenever the interpreter
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3394 prints a primary or secondary prompt. The current line can be edited
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3395 using the conventional Emacs control characters. The most important
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3396 of these are: C-A (Control-A) moves the cursor to the beginning of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3397 line, C-E to the end, C-B moves it one position to the left, C-F to
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3398 the right. Backspace erases the character to the left of the cursor,
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3399 C-D the character to its right. C-K kills (erases) the rest of the
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3400 line to the right of the cursor, C-Y yanks back the last killed
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3401 string. C-underscore undoes the last change you made; it can be
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3402 repeated for cumulative effect.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3403
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3404 \subsection{History Substitution}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3405
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3406 History substitution works as follows. All non-empty input lines
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3407 issued are saved in a history buffer, and when a new prompt is given
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3408 you are positioned on a new line at the bottom of this buffer. C-P
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3409 moves one line up (back) in the history buffer, C-N moves one down.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3410 Any line in the history buffer can be edited; an asterisk appears in
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3411 front of the prompt to mark a line as modified. Pressing the Return
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3412 key passes the current line to the interpreter. C-R starts an
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3413 incremental reverse search; C-S starts a forward search.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3414
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3415 \subsection{Key Bindings}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3416
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3417 The key bindings and some other parameters of the Readline library can
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3418 be customized by placing commands in an initialization file called
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3419 {\tt \$HOME/.inputrc}. Key bindings have the form
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3420
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3421 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3422 key-name: function-name
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3423 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3424 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3425 or
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3426
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3427 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3428 "string": function-name
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3429 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3430 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3431 and options can be set with
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3432
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3433 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3434 set option-name value
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3435 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3436 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3437 For example:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3438
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3439 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3440 # I prefer vi-style editing:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3441 set editing-mode vi
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3442 # Edit using a single line:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3443 set horizontal-scroll-mode On
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3444 # Rebind some keys:
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3445 Meta-h: backward-kill-word
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3446 "\C-u": universal-argument
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3447 "\C-x\C-r": re-read-init-file
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3448 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3449 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3450 Note that the default binding for TAB in Python is to insert a TAB
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3451 instead of Readline's default filename completion function. If you
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3452 insist, you can override this by putting
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3453
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3454 \bcode\begin{verbatim}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3455 TAB: complete
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3456 \end{verbatim}\ecode
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3457 %
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3458 in your {\tt \$HOME/.inputrc}. (Of course, this makes it hard to type
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3459 indented continuation lines...)
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3460
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3461 \subsection{Commentary}
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3462
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3463 This facility is an enormous step forward compared to previous
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3464 versions of the interpreter; however, some wishes are left: It would
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3465 be nice if the proper indentation were suggested on continuation lines
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3466 (the parser knows if an indent token is required next). The
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3467 completion mechanism might use the interpreter's symbol table. A
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3468 command to check (or even suggest) matching parentheses, quotes etc.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3469 would also be useful.
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3470
d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3471 XXX Lele Gaifax's readline module, which adds name completion...
4118 a86407b3c3ac Version number; started chapter on what's new in 1.4 Guido van Rossum <guido@python.org> parents: 3659 diff changeset	3472
112 d8a1b6456212 Initial revision Guido van Rossum <guido@python.org> parents: diff changeset	3473 \end{document}
5813 d320ca843512 New version (interim) by AMK. Guido van Rossum <guido@python.org> parents: 4727 diff changeset	3474

Mercurial > cpython-lru_cache-weakref

annotate Doc/tut.tex @ 5817:48b94de85bf3 legacy-trunk