Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 1 | \documentclass{manual} |
Fred Drake | 1b0b2a4 | 2001-03-13 17:56:08 +0000 | [diff] [blame] | 2 | \usepackage[T1]{fontenc} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4 | % Things to do: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 5 | % Should really move the Python startup file info to an appendix |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 7 | \title{Python Tutorial} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 8 | |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 9 | \input{boilerplate} |
Guido van Rossum | 83eb962 | 1993-11-23 16:28:45 +0000 | [diff] [blame] | 10 | |
Skip Montanaro | 40d4bc5 | 2003-09-24 16:53:02 +0000 | [diff] [blame] | 11 | \makeindex |
| 12 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 13 | \begin{document} |
| 14 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 15 | \maketitle |
| 16 | |
Fred Drake | 9f86b66 | 1998-07-28 21:55:19 +0000 | [diff] [blame] | 17 | \ifhtml |
| 18 | \chapter*{Front Matter\label{front}} |
| 19 | \fi |
| 20 | |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 21 | \input{copyright} |
| 22 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 23 | \begin{abstract} |
| 24 | |
| 25 | \noindent |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 26 | Python is an easy to learn, powerful programming language. It has |
| 27 | efficient high-level data structures and a simple but effective |
| 28 | approach to object-oriented programming. Python's elegant syntax and |
| 29 | dynamic typing, together with its interpreted nature, make it an ideal |
| 30 | language for scripting and rapid application development in many areas |
| 31 | on most platforms. |
| 32 | |
| 33 | The Python interpreter and the extensive standard library are freely |
| 34 | available in source or binary form for all major platforms from the |
Fred Drake | 17f690f | 2001-07-14 02:14:42 +0000 | [diff] [blame] | 35 | Python Web site, \url{http://www.python.org/}, and can be freely |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 36 | distributed. The same site also contains distributions of and |
| 37 | pointers to many free third party Python modules, programs and tools, |
| 38 | and additional documentation. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 39 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 40 | The Python interpreter is easily extended with new functions and data |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 41 | types implemented in C or \Cpp{} (or other languages callable from C). |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 42 | Python is also suitable as an extension language for customizable |
| 43 | applications. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 44 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 45 | This tutorial introduces the reader informally to the basic concepts |
| 46 | and features of the Python language and system. It helps to have a |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 47 | Python interpreter handy for hands-on experience, but all examples are |
| 48 | self-contained, so the tutorial can be read off-line as well. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 49 | |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 50 | For a description of standard objects and modules, see the |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 51 | \citetitle[../lib/lib.html]{Python Library Reference} document. The |
| 52 | \citetitle[../ref/ref.html]{Python Reference Manual} gives a more |
| 53 | formal definition of the language. To write extensions in C or |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 54 | \Cpp, read \citetitle[../ext/ext.html]{Extending and Embedding the |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 55 | Python Interpreter} and \citetitle[../api/api.html]{Python/C API |
| 56 | Reference}. There are also several books covering Python in depth. |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 57 | |
| 58 | This tutorial does not attempt to be comprehensive and cover every |
| 59 | single feature, or even every commonly used feature. Instead, it |
| 60 | introduces many of Python's most noteworthy features, and will give |
| 61 | you a good idea of the language's flavor and style. After reading it, |
| 62 | you will be able to read and write Python modules and programs, and |
| 63 | you will be ready to learn more about the various Python library |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 64 | modules described in the \citetitle[../lib/lib.html]{Python Library |
| 65 | Reference}. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 66 | |
| 67 | \end{abstract} |
| 68 | |
Fred Drake | 4d4f9e7 | 1998-01-13 22:25:02 +0000 | [diff] [blame] | 69 | \tableofcontents |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 70 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 71 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 72 | \chapter{Whetting Your Appetite \label{intro}} |
Guido van Rossum | 3a26dd8 | 1996-10-24 22:12:48 +0000 | [diff] [blame] | 73 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 74 | If you ever wrote a large shell script, you probably know this |
| 75 | feeling: you'd love to add yet another feature, but it's already so |
| 76 | slow, and so big, and so complicated; or the feature involves a system |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 77 | call or other function that is only accessible from C \ldots Usually |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 78 | the problem at hand isn't serious enough to warrant rewriting the |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 79 | script in C; perhaps the problem requires variable-length strings or |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 80 | other data types (like sorted lists of file names) that are easy in |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 81 | the shell but lots of work to implement in C, or perhaps you're not |
| 82 | sufficiently familiar with C. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 83 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 84 | Another situation: perhaps you have to work with several C libraries, |
| 85 | and the usual C write/compile/test/re-compile cycle is too slow. You |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 86 | need to develop software more quickly. Possibly perhaps you've |
| 87 | written a program that could use an extension language, and you don't |
| 88 | want to design a language, write and debug an interpreter for it, then |
| 89 | tie it into your application. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 90 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 91 | In such cases, Python may be just the language for you. Python is |
| 92 | simple to use, but it is a real programming language, offering much |
| 93 | more structure and support for large programs than the shell has. On |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 94 | the other hand, it also offers much more error checking than C, and, |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 95 | being a \emph{very-high-level language}, it has high-level data types |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 96 | built in, such as flexible arrays and dictionaries that would cost you |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 97 | days to implement efficiently in C. Because of its more general data |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 98 | types Python is applicable to a much larger problem domain than |
| 99 | \emph{Awk} or even \emph{Perl}, yet many things are at least as easy |
| 100 | in Python as in those languages. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 101 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 102 | Python allows you to split up your program in modules that can be |
| 103 | reused in other Python programs. It comes with a large collection of |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 104 | standard modules that you can use as the basis of your programs --- or |
| 105 | as examples to start learning to program in Python. There are also |
| 106 | built-in modules that provide things like file I/O, system calls, |
Fred Drake | 17f690f | 2001-07-14 02:14:42 +0000 | [diff] [blame] | 107 | sockets, and even interfaces to graphical user interface toolkits like Tk. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 108 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 109 | Python is an interpreted language, which can save you considerable time |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 110 | during program development because no compilation and linking is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 111 | necessary. The interpreter can be used interactively, which makes it |
| 112 | easy to experiment with features of the language, to write throw-away |
| 113 | programs, or to test functions during bottom-up program development. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 114 | It is also a handy desk calculator. |
| 115 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 116 | Python allows writing very compact and readable programs. Programs |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 117 | written in Python are typically much shorter than equivalent C or |
| 118 | \Cpp{} programs, for several reasons: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 119 | \begin{itemize} |
| 120 | \item |
| 121 | the high-level data types allow you to express complex operations in a |
| 122 | single statement; |
| 123 | \item |
Raymond Hettinger | 57d7128 | 2003-08-30 23:21:32 +0000 | [diff] [blame] | 124 | statement grouping is done by indentation instead of beginning and ending |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 125 | brackets; |
| 126 | \item |
| 127 | no variable or argument declarations are necessary. |
| 128 | \end{itemize} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 129 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 130 | Python is \emph{extensible}: if you know how to program in C it is easy |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 131 | to add a new built-in function or module to the interpreter, either to |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 132 | perform critical operations at maximum speed, or to link Python |
| 133 | programs to libraries that may only be available in binary form (such |
| 134 | as a vendor-specific graphics library). Once you are really hooked, |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 135 | you can link the Python interpreter into an application written in C |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 136 | and use it as an extension or command language for that application. |
| 137 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 138 | By the way, the language is named after the BBC show ``Monty Python's |
| 139 | Flying Circus'' and has nothing to do with nasty reptiles. Making |
| 140 | references to Monty Python skits in documentation is not only allowed, |
Guido van Rossum | dccc298 | 1997-12-30 04:40:25 +0000 | [diff] [blame] | 141 | it is encouraged! |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 142 | |
Fred Drake | 2664cbb | 2003-06-20 14:27:27 +0000 | [diff] [blame] | 143 | %\section{Where From Here \label{where}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 144 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 145 | Now that you are all excited about Python, you'll want to examine it |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 146 | in some more detail. Since the best way to learn a language is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 147 | using it, you are invited here to do so. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 148 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 149 | In the next chapter, the mechanics of using the interpreter are |
| 150 | explained. This is rather mundane information, but essential for |
| 151 | trying out the examples shown later. |
| 152 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 153 | The rest of the tutorial introduces various features of the Python |
Fred Drake | f64f8a0 | 1999-06-10 15:30:21 +0000 | [diff] [blame] | 154 | language and system through examples, beginning with simple |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 155 | expressions, statements and data types, through functions and modules, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 156 | and finally touching upon advanced concepts like exceptions |
| 157 | and user-defined classes. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 158 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 159 | \chapter{Using the Python Interpreter \label{using}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 160 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 161 | \section{Invoking the Interpreter \label{invoking}} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 162 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 163 | The Python interpreter is usually installed as |
| 164 | \file{/usr/local/bin/python} on those machines where it is available; |
| 165 | putting \file{/usr/local/bin} in your \UNIX{} shell's search path |
| 166 | makes it possible to start it by typing the command |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 167 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 168 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 169 | python |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 170 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 171 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 172 | to the shell. Since the choice of the directory where the interpreter |
| 173 | lives is an installation option, other places are possible; check with |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 174 | your local Python guru or system administrator. (E.g., |
| 175 | \file{/usr/local/python} is a popular alternative location.) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 176 | |
Fred Drake | 5d6e402 | 2001-04-11 04:38:34 +0000 | [diff] [blame] | 177 | Typing an end-of-file character (\kbd{Control-D} on \UNIX, |
Martin v. Löwis | 36a4d8c | 2002-10-10 18:24:54 +0000 | [diff] [blame] | 178 | \kbd{Control-Z} on Windows) at the primary prompt causes the |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 179 | interpreter to exit with a zero exit status. If that doesn't work, |
| 180 | you can exit the interpreter by typing the following commands: |
| 181 | \samp{import sys; sys.exit()}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 182 | |
| 183 | The interpreter's line-editing features usually aren't very |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 184 | sophisticated. On \UNIX, whoever installed the interpreter may have |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 185 | enabled support for the GNU readline library, which adds more |
| 186 | elaborate interactive editing and history features. Perhaps the |
| 187 | quickest check to see whether command line editing is supported is |
| 188 | typing Control-P to the first Python prompt you get. If it beeps, you |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 189 | have command line editing; see Appendix \ref{interacting} for an |
| 190 | introduction to the keys. If nothing appears to happen, or if |
| 191 | \code{\^P} is echoed, command line editing isn't available; you'll |
| 192 | only be able to use backspace to remove characters from the current |
| 193 | line. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 194 | |
Fred Drake | 6dc2aae | 1996-12-13 21:56:03 +0000 | [diff] [blame] | 195 | The interpreter operates somewhat like the \UNIX{} shell: when called |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 196 | with standard input connected to a tty device, it reads and executes |
| 197 | commands interactively; when called with a file name argument or with |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 198 | a file as standard input, it reads and executes a \emph{script} from |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 199 | that file. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 200 | |
Raymond Hettinger | c2a5cb2 | 2003-08-23 03:49:08 +0000 | [diff] [blame] | 201 | A second way of starting the interpreter is |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 202 | \samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which |
| 203 | executes the statement(s) in \var{command}, analogous to the shell's |
| 204 | \programopt{-c} option. Since Python statements often contain spaces |
| 205 | or other characters that are special to the shell, it is best to quote |
| 206 | \var{command} in its entirety with double quotes. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 207 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 208 | Note that there is a difference between \samp{python file} and |
| 209 | \samp{python <file}. In the latter case, input requests from the |
Fred Drake | 6bab183 | 2003-05-20 15:28:58 +0000 | [diff] [blame] | 210 | program, such as calls to \function{input()} and \function{raw_input()}, are |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 211 | satisfied from \emph{file}. Since this file has already been read |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 212 | until the end by the parser before the program starts executing, the |
Fred Drake | 5d6e402 | 2001-04-11 04:38:34 +0000 | [diff] [blame] | 213 | program will encounter end-of-file immediately. In the former case |
| 214 | (which is usually what you want) they are satisfied from whatever file |
| 215 | or device is connected to standard input of the Python interpreter. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 216 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 217 | When a script file is used, it is sometimes useful to be able to run |
| 218 | the script and enter interactive mode afterwards. This can be done by |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 219 | passing \programopt{-i} before the script. (This does not work if the |
| 220 | script is read from standard input, for the same reason as explained |
| 221 | in the previous paragraph.) |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 222 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 223 | \subsection{Argument Passing \label{argPassing}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 224 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 225 | When known to the interpreter, the script name and additional |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 226 | arguments thereafter are passed to the script in the variable |
| 227 | \code{sys.argv}, which is a list of strings. Its length is at least |
| 228 | one; when no script and no arguments are given, \code{sys.argv[0]} is |
| 229 | an empty string. When the script name is given as \code{'-'} (meaning |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 230 | standard input), \code{sys.argv[0]} is set to \code{'-'}. When |
| 231 | \programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to |
| 232 | \code{'-c'}. Options found after \programopt{-c} \var{command} are |
| 233 | not consumed by the Python interpreter's option processing but left in |
| 234 | \code{sys.argv} for the command to handle. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 235 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 236 | \subsection{Interactive Mode \label{interactive}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 237 | |
Guido van Rossum | dd01080 | 1991-06-07 14:31:11 +0000 | [diff] [blame] | 238 | When commands are read from a tty, the interpreter is said to be in |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 239 | \emph{interactive mode}. In this mode it prompts for the next command |
| 240 | with the \emph{primary prompt}, usually three greater-than signs |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 241 | (\samp{>\code{>}>~}); for continuation lines it prompts with the |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 242 | \emph{secondary prompt}, by default three dots (\samp{...~}). |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 243 | The interpreter prints a welcome message stating its version number |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 244 | and a copyright notice before printing the first prompt: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 245 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 246 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 247 | python |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 248 | Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5 |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 249 | Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 250 | >>> |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 251 | \end{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 252 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 253 | Continuation lines are needed when entering a multi-line construct. |
| 254 | As an example, take a look at this \keyword{if} statement: |
| 255 | |
| 256 | \begin{verbatim} |
| 257 | >>> the_world_is_flat = 1 |
| 258 | >>> if the_world_is_flat: |
| 259 | ... print "Be careful not to fall off!" |
| 260 | ... |
| 261 | Be careful not to fall off! |
| 262 | \end{verbatim} |
| 263 | |
| 264 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 265 | \section{The Interpreter and Its Environment \label{interp}} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 266 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 267 | \subsection{Error Handling \label{error}} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 268 | |
| 269 | When an error occurs, the interpreter prints an error |
| 270 | message and a stack trace. In interactive mode, it then returns to |
| 271 | the primary prompt; when input came from a file, it exits with a |
| 272 | nonzero exit status after printing |
Fred Drake | 6bab183 | 2003-05-20 15:28:58 +0000 | [diff] [blame] | 273 | the stack trace. (Exceptions handled by an \keyword{except} clause in a |
| 274 | \keyword{try} statement are not errors in this context.) Some errors are |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 275 | unconditionally fatal and cause an exit with a nonzero exit; this |
| 276 | applies to internal inconsistencies and some cases of running out of |
| 277 | memory. All error messages are written to the standard error stream; |
| 278 | normal output from the executed commands is written to standard |
| 279 | output. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 280 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 281 | Typing the interrupt character (usually Control-C or DEL) to the |
| 282 | primary or secondary prompt cancels the input and returns to the |
Fred Drake | 93aa0f2 | 1999-04-05 21:39:17 +0000 | [diff] [blame] | 283 | primary prompt.\footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 284 | A problem with the GNU Readline package may prevent this. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 285 | } |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 286 | Typing an interrupt while a command is executing raises the |
Fred Drake | 6bab183 | 2003-05-20 15:28:58 +0000 | [diff] [blame] | 287 | \exception{KeyboardInterrupt} exception, which may be handled by a |
| 288 | \keyword{try} statement. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 289 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 290 | \subsection{Executable Python Scripts \label{scripts}} |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 291 | |
Fred Drake | 6dc2aae | 1996-12-13 21:56:03 +0000 | [diff] [blame] | 292 | On BSD'ish \UNIX{} systems, Python scripts can be made directly |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 293 | executable, like shell scripts, by putting the line |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 294 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 295 | \begin{verbatim} |
Fred Drake | 9e63faa | 1997-10-15 14:37:24 +0000 | [diff] [blame] | 296 | #! /usr/bin/env python |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 297 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 298 | |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 299 | (assuming that the interpreter is on the user's \envvar{PATH}) at the |
| 300 | beginning of the script and giving the file an executable mode. The |
Fred Drake | dfda8d7 | 2003-07-07 21:00:29 +0000 | [diff] [blame] | 301 | \samp{\#!} must be the first two characters of the file. On some |
| 302 | platforms, this first line must end with a \UNIX-style line ending |
| 303 | (\character{\e n}), not a Mac OS (\character{\e r}) or Windows |
| 304 | (\character{\e r\e n}) line ending. Note that |
Fred Drake | bdadf0f | 1999-04-29 13:20:25 +0000 | [diff] [blame] | 305 | the hash, or pound, character, \character{\#}, is used to start a |
| 306 | comment in Python. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 307 | |
Fred Drake | dfda8d7 | 2003-07-07 21:00:29 +0000 | [diff] [blame] | 308 | The script can be given a executable mode, or permission, using the |
| 309 | \program{chmod} command: |
| 310 | |
| 311 | \begin{verbatim} |
| 312 | $ chmod +x myscript.py |
| 313 | \end{verbatim} % $ <-- bow to font-lock |
| 314 | |
| 315 | |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 316 | \subsection{Source Code Encoding} |
| 317 | |
Fred Drake | dfda8d7 | 2003-07-07 21:00:29 +0000 | [diff] [blame] | 318 | It is possible to use encodings different than \ASCII{} in Python source |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 319 | files. The best way to do it is to put one more special comment line |
Skip Montanaro | 32a5e87 | 2003-06-29 16:01:51 +0000 | [diff] [blame] | 320 | right after the \code{\#!} line to define the source file encoding: |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 321 | |
| 322 | \begin{verbatim} |
| 323 | # -*- coding: iso-8859-1 -*- |
| 324 | \end{verbatim} |
| 325 | |
Skip Montanaro | 32a5e87 | 2003-06-29 16:01:51 +0000 | [diff] [blame] | 326 | With that declaration, all characters in the source file will be treated as |
| 327 | {}\code{iso-8859-1}, and it will be |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 328 | possible to directly write Unicode string literals in the selected |
Skip Montanaro | 32a5e87 | 2003-06-29 16:01:51 +0000 | [diff] [blame] | 329 | encoding. The list of possible encodings can be found in the |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 330 | \citetitle[../lib/lib.html]{Python Library Reference}, in the section |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 331 | on \ulink{\module{codecs}}{../lib/module-codecs.html}. |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 332 | |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 333 | If your editor supports saving files as \code{UTF-8} with a UTF-8 |
| 334 | \emph{byte order mark} (aka BOM), you can use that instead of an |
Skip Montanaro | 32a5e87 | 2003-06-29 16:01:51 +0000 | [diff] [blame] | 335 | encoding declaration. IDLE supports this capability if |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 336 | \code{Options/General/Default Source Encoding/UTF-8} is set. Notice |
| 337 | that this signature is not understood in older Python releases (2.2 |
| 338 | and earlier), and also not understood by the operating system for |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 339 | \code{\#!} files. |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 340 | |
Skip Montanaro | 32a5e87 | 2003-06-29 16:01:51 +0000 | [diff] [blame] | 341 | By using UTF-8 (either through the signature or an encoding |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 342 | declaration), characters of most languages in the world can be used |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 343 | simultaneously in string literals and comments. Using non-\ASCII |
Martin v. Löwis | 7928f38 | 2003-06-28 08:11:55 +0000 | [diff] [blame] | 344 | characters in identifiers is not supported. To display all these |
| 345 | characters properly, your editor must recognize that the file is |
| 346 | UTF-8, and it must use a font that supports all the characters in the |
| 347 | file. |
| 348 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 349 | \subsection{The Interactive Startup File \label{startup}} |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 350 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 351 | % XXX This should probably be dumped in an appendix, since most people |
| 352 | % don't use Python interactively in non-trivial ways. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 353 | |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 354 | When you use Python interactively, it is frequently handy to have some |
| 355 | standard commands executed every time the interpreter is started. You |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 356 | can do this by setting an environment variable named |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 357 | \envvar{PYTHONSTARTUP} to the name of a file containing your start-up |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 358 | commands. This is similar to the \file{.profile} feature of the |
| 359 | \UNIX{} shells. |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 360 | |
| 361 | This file is only read in interactive sessions, not when Python reads |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 362 | commands from a script, and not when \file{/dev/tty} is given as the |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 363 | explicit source of commands (which otherwise behaves like an |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 364 | interactive session). It is executed in the same namespace where |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 365 | interactive commands are executed, so that objects that it defines or |
| 366 | imports can be used without qualification in the interactive session. |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 367 | You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in |
Guido van Rossum | 7b3c8a1 | 1992-09-08 09:20:13 +0000 | [diff] [blame] | 368 | this file. |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 369 | |
| 370 | If you want to read an additional start-up file from the current |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 371 | directory, you can program this in the global start-up file using code |
| 372 | like \samp{if os.path.isfile('.pythonrc.py'): |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 373 | execfile('.pythonrc.py')}. If you want to use the startup file in a |
| 374 | script, you must do this explicitly in the script: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 375 | |
| 376 | \begin{verbatim} |
| 377 | import os |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 378 | filename = os.environ.get('PYTHONSTARTUP') |
| 379 | if filename and os.path.isfile(filename): |
| 380 | execfile(filename) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 381 | \end{verbatim} |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 382 | |
Fred Drake | 7238988 | 1998-04-13 01:31:10 +0000 | [diff] [blame] | 383 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 384 | \chapter{An Informal Introduction to Python \label{informal}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 385 | |
| 386 | In the following examples, input and output are distinguished by the |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 387 | presence or absence of prompts (\samp{>\code{>}>~} and \samp{...~}): to repeat |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 388 | the example, you must type everything after the prompt, when the |
| 389 | prompt appears; lines that do not begin with a prompt are output from |
Fred Drake | bdadf0f | 1999-04-29 13:20:25 +0000 | [diff] [blame] | 390 | the interpreter. % |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 391 | %\footnote{ |
| 392 | % I'd prefer to use different fonts to distinguish input |
| 393 | % from output, but the amount of LaTeX hacking that would require |
| 394 | % is currently beyond my ability. |
| 395 | %} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 396 | Note that a secondary prompt on a line by itself in an example means |
| 397 | you must type a blank line; this is used to end a multi-line command. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 398 | |
Fred Drake | bdadf0f | 1999-04-29 13:20:25 +0000 | [diff] [blame] | 399 | Many of the examples in this manual, even those entered at the |
| 400 | interactive prompt, include comments. Comments in Python start with |
| 401 | the hash character, \character{\#}, and extend to the end of the |
| 402 | physical line. A comment may appear at the start of a line or |
| 403 | following whitespace or code, but not within a string literal. A hash |
| 404 | character within a string literal is just a hash character. |
| 405 | |
| 406 | Some examples: |
| 407 | |
| 408 | \begin{verbatim} |
| 409 | # this is the first comment |
| 410 | SPAM = 1 # and this is the second comment |
| 411 | # ... and now a third! |
| 412 | STRING = "# This is not a comment." |
| 413 | \end{verbatim} |
| 414 | |
| 415 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 416 | \section{Using Python as a Calculator \label{calculator}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 417 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 418 | Let's try some simple Python commands. Start the interpreter and wait |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 419 | for the primary prompt, \samp{>\code{>}>~}. (It shouldn't take long.) |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 420 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 421 | \subsection{Numbers \label{numbers}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 422 | |
| 423 | The interpreter acts as a simple calculator: you can type an |
| 424 | expression at it and it will write the value. Expression syntax is |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 425 | straightforward: the operators \code{+}, \code{-}, \code{*} and |
| 426 | \code{/} work just like in most other languages (for example, Pascal |
| 427 | or C); parentheses can be used for grouping. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 428 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 429 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 430 | >>> 2+2 |
| 431 | 4 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 432 | >>> # This is a comment |
| 433 | ... 2+2 |
| 434 | 4 |
| 435 | >>> 2+2 # and a comment on the same line as code |
| 436 | 4 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 437 | >>> (50-5*6)/4 |
| 438 | 5 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 439 | >>> # Integer division returns the floor: |
| 440 | ... 7/3 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 441 | 2 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 442 | >>> 7/-3 |
| 443 | -3 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 444 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 445 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 446 | Like in C, the equal sign (\character{=}) is used to assign a value to a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 447 | variable. The value of an assignment is not written: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 448 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 449 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 450 | >>> width = 20 |
| 451 | >>> height = 5*9 |
| 452 | >>> width * height |
| 453 | 900 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 454 | \end{verbatim} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 455 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 456 | A value can be assigned to several variables simultaneously: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 457 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 458 | \begin{verbatim} |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 459 | >>> x = y = z = 0 # Zero x, y and z |
| 460 | >>> x |
| 461 | 0 |
| 462 | >>> y |
| 463 | 0 |
| 464 | >>> z |
| 465 | 0 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 466 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 467 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 468 | There is full support for floating point; operators with mixed type |
| 469 | operands convert the integer operand to floating point: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 470 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 471 | \begin{verbatim} |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 472 | >>> 3 * 3.75 / 1.5 |
| 473 | 7.5 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 474 | >>> 7.0 / 2 |
| 475 | 3.5 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 476 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 477 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 478 | Complex numbers are also supported; imaginary numbers are written with |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 479 | a suffix of \samp{j} or \samp{J}. Complex numbers with a nonzero |
| 480 | real component are written as \samp{(\var{real}+\var{imag}j)}, or can |
| 481 | be created with the \samp{complex(\var{real}, \var{imag})} function. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 482 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 483 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 484 | >>> 1j * 1J |
| 485 | (-1+0j) |
| 486 | >>> 1j * complex(0,1) |
| 487 | (-1+0j) |
| 488 | >>> 3+1j*3 |
| 489 | (3+3j) |
| 490 | >>> (3+1j)*3 |
| 491 | (9+3j) |
| 492 | >>> (1+2j)/(1+1j) |
| 493 | (1.5+0.5j) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 494 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 495 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 496 | Complex numbers are always represented as two floating point numbers, |
| 497 | the real and imaginary part. To extract these parts from a complex |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 498 | number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 499 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 500 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 501 | >>> a=1.5+0.5j |
| 502 | >>> a.real |
| 503 | 1.5 |
| 504 | >>> a.imag |
| 505 | 0.5 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 506 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 507 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 508 | The conversion functions to floating point and integer |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 509 | (\function{float()}, \function{int()} and \function{long()}) don't |
| 510 | work for complex numbers --- there is no one correct way to convert a |
| 511 | complex number to a real number. Use \code{abs(\var{z})} to get its |
| 512 | magnitude (as a float) or \code{z.real} to get its real part. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 513 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 514 | \begin{verbatim} |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 515 | >>> a=3.0+4.0j |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 516 | >>> float(a) |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 517 | Traceback (most recent call last): |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 518 | File "<stdin>", line 1, in ? |
Raymond Hettinger | 57d7128 | 2003-08-30 23:21:32 +0000 | [diff] [blame] | 519 | TypeError: can't convert complex to float; use abs(z) |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 520 | >>> a.real |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 521 | 3.0 |
| 522 | >>> a.imag |
| 523 | 4.0 |
| 524 | >>> abs(a) # sqrt(a.real**2 + a.imag**2) |
| 525 | 5.0 |
| 526 | >>> |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 527 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 528 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 529 | In interactive mode, the last printed expression is assigned to the |
| 530 | variable \code{_}. This means that when you are using Python as a |
| 531 | desk calculator, it is somewhat easier to continue calculations, for |
| 532 | example: |
| 533 | |
| 534 | \begin{verbatim} |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 535 | >>> tax = 12.5 / 100 |
| 536 | >>> price = 100.50 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 537 | >>> price * tax |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 538 | 12.5625 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 539 | >>> price + _ |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 540 | 113.0625 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 541 | >>> round(_, 2) |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 542 | 113.06 |
| 543 | >>> |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 544 | \end{verbatim} |
| 545 | |
| 546 | This variable should be treated as read-only by the user. Don't |
| 547 | explicitly assign a value to it --- you would create an independent |
| 548 | local variable with the same name masking the built-in variable with |
| 549 | its magic behavior. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 550 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 551 | \subsection{Strings \label{strings}} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 552 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 553 | Besides numbers, Python can also manipulate strings, which can be |
| 554 | expressed in several ways. They can be enclosed in single quotes or |
| 555 | double quotes: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 556 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 557 | \begin{verbatim} |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 558 | >>> 'spam eggs' |
| 559 | 'spam eggs' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 560 | >>> 'doesn\'t' |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 561 | "doesn't" |
| 562 | >>> "doesn't" |
| 563 | "doesn't" |
| 564 | >>> '"Yes," he said.' |
| 565 | '"Yes," he said.' |
| 566 | >>> "\"Yes,\" he said." |
| 567 | '"Yes," he said.' |
| 568 | >>> '"Isn\'t," she said.' |
| 569 | '"Isn\'t," she said.' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 570 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 571 | |
Fred Drake | ba5c41d | 2001-09-06 18:41:15 +0000 | [diff] [blame] | 572 | String literals can span multiple lines in several ways. Continuation |
| 573 | lines can be used, with a backslash as the last character on the line |
| 574 | indicating that the next line is a logical continuation of the line: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 575 | |
| 576 | \begin{verbatim} |
| 577 | hello = "This is a rather long string containing\n\ |
| 578 | several lines of text just as you would do in C.\n\ |
| 579 | Note that whitespace at the beginning of the line is\ |
Fred Drake | ba5c41d | 2001-09-06 18:41:15 +0000 | [diff] [blame] | 580 | significant." |
| 581 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 582 | print hello |
| 583 | \end{verbatim} |
| 584 | |
Fred Drake | ba5c41d | 2001-09-06 18:41:15 +0000 | [diff] [blame] | 585 | Note that newlines would still need to be embedded in the string using |
| 586 | \code{\e n}; the newline following the trailing backslash is |
| 587 | discarded. This example would print the following: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 588 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 589 | \begin{verbatim} |
| 590 | This is a rather long string containing |
| 591 | several lines of text just as you would do in C. |
| 592 | Note that whitespace at the beginning of the line is significant. |
| 593 | \end{verbatim} |
| 594 | |
Fred Drake | ba5c41d | 2001-09-06 18:41:15 +0000 | [diff] [blame] | 595 | If we make the string literal a ``raw'' string, however, the |
| 596 | \code{\e n} sequences are not converted to newlines, but the backslash |
| 597 | at the end of the line, and the newline character in the source, are |
| 598 | both included in the string as data. Thus, the example: |
| 599 | |
| 600 | \begin{verbatim} |
| 601 | hello = r"This is a rather long string containing\n\ |
| 602 | several lines of text much as you would do in C." |
| 603 | |
| 604 | print hello |
| 605 | \end{verbatim} |
| 606 | |
| 607 | would print: |
| 608 | |
| 609 | \begin{verbatim} |
| 610 | This is a rather long string containing\n\ |
| 611 | several lines of text much as you would do in C. |
| 612 | \end{verbatim} |
| 613 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 614 | Or, strings can be surrounded in a pair of matching triple-quotes: |
Fred Drake | ba5c41d | 2001-09-06 18:41:15 +0000 | [diff] [blame] | 615 | \code{"""} or \code{'\code{'}'}. End of lines do not need to be escaped |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 616 | when using triple-quotes, but they will be included in the string. |
| 617 | |
| 618 | \begin{verbatim} |
| 619 | print """ |
| 620 | Usage: thingy [OPTIONS] |
| 621 | -h Display this usage message |
| 622 | -H hostname Hostname to connect to |
| 623 | """ |
| 624 | \end{verbatim} |
| 625 | |
| 626 | produces the following output: |
| 627 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 628 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 629 | Usage: thingy [OPTIONS] |
| 630 | -h Display this usage message |
| 631 | -H hostname Hostname to connect to |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 632 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 633 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 634 | The interpreter prints the result of string operations in the same way |
| 635 | as they are typed for input: inside quotes, and with quotes and other |
| 636 | funny characters escaped by backslashes, to show the precise |
| 637 | value. The string is enclosed in double quotes if the string contains |
| 638 | a single quote and no double quotes, else it's enclosed in single |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 639 | quotes. (The \keyword{print} statement, described later, can be used |
| 640 | to write strings without quotes or escapes.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 641 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 642 | Strings can be concatenated (glued together) with the |
| 643 | \code{+} operator, and repeated with \code{*}: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 644 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 645 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 646 | >>> word = 'Help' + 'A' |
| 647 | >>> word |
| 648 | 'HelpA' |
| 649 | >>> '<' + word*5 + '>' |
| 650 | '<HelpAHelpAHelpAHelpAHelpA>' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 651 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 652 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 653 | Two string literals next to each other are automatically concatenated; |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 654 | the first line above could also have been written \samp{word = 'Help' |
Guido van Rossum | e51aa5b | 1999-01-06 23:14:14 +0000 | [diff] [blame] | 655 | 'A'}; this only works with two literals, not with arbitrary string |
| 656 | expressions: |
| 657 | |
| 658 | \begin{verbatim} |
| 659 | >>> 'str' 'ing' # <- This is ok |
| 660 | 'string' |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 661 | >>> 'str'.strip() + 'ing' # <- This is ok |
Guido van Rossum | e51aa5b | 1999-01-06 23:14:14 +0000 | [diff] [blame] | 662 | 'string' |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 663 | >>> 'str'.strip() 'ing' # <- This is invalid |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 664 | File "<stdin>", line 1, in ? |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 665 | 'str'.strip() 'ing' |
| 666 | ^ |
Guido van Rossum | e51aa5b | 1999-01-06 23:14:14 +0000 | [diff] [blame] | 667 | SyntaxError: invalid syntax |
| 668 | \end{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 669 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 670 | Strings can be subscripted (indexed); like in C, the first character |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 671 | of a string has subscript (index) 0. There is no separate character |
| 672 | type; a character is simply a string of size one. Like in Icon, |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 673 | substrings can be specified with the \emph{slice notation}: two indices |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 674 | separated by a colon. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 675 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 676 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 677 | >>> word[4] |
| 678 | 'A' |
| 679 | >>> word[0:2] |
| 680 | 'He' |
| 681 | >>> word[2:4] |
| 682 | 'lp' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 683 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 684 | |
Raymond Hettinger | 60de2e8 | 2003-03-12 04:46:52 +0000 | [diff] [blame] | 685 | Slice indices have useful defaults; an omitted first index defaults to |
| 686 | zero, an omitted second index defaults to the size of the string being |
| 687 | sliced. |
| 688 | |
| 689 | \begin{verbatim} |
| 690 | >>> word[:2] # The first two characters |
| 691 | 'He' |
| 692 | >>> word[2:] # All but the first two characters |
| 693 | 'lpA' |
| 694 | \end{verbatim} |
| 695 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 696 | Unlike a C string, Python strings cannot be changed. Assigning to an |
| 697 | indexed position in the string results in an error: |
| 698 | |
| 699 | \begin{verbatim} |
| 700 | >>> word[0] = 'x' |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 701 | Traceback (most recent call last): |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 702 | File "<stdin>", line 1, in ? |
| 703 | TypeError: object doesn't support item assignment |
Fred Drake | 67fdaa4 | 2001-03-06 07:19:34 +0000 | [diff] [blame] | 704 | >>> word[:1] = 'Splat' |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 705 | Traceback (most recent call last): |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 706 | File "<stdin>", line 1, in ? |
| 707 | TypeError: object doesn't support slice assignment |
| 708 | \end{verbatim} |
| 709 | |
| 710 | However, creating a new string with the combined content is easy and |
| 711 | efficient: |
| 712 | |
| 713 | \begin{verbatim} |
| 714 | >>> 'x' + word[1:] |
| 715 | 'xelpA' |
Fred Drake | 67fdaa4 | 2001-03-06 07:19:34 +0000 | [diff] [blame] | 716 | >>> 'Splat' + word[4] |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 717 | 'SplatA' |
| 718 | \end{verbatim} |
| 719 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 720 | Here's a useful invariant of slice operations: |
| 721 | \code{s[:i] + s[i:]} equals \code{s}. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 722 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 723 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 724 | >>> word[:2] + word[2:] |
| 725 | 'HelpA' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 726 | >>> word[:3] + word[3:] |
| 727 | 'HelpA' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 728 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 729 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 730 | Degenerate slice indices are handled gracefully: an index that is too |
| 731 | large is replaced by the string size, an upper bound smaller than the |
| 732 | lower bound returns an empty string. |
| 733 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 734 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 735 | >>> word[1:100] |
| 736 | 'elpA' |
| 737 | >>> word[10:] |
| 738 | '' |
| 739 | >>> word[2:1] |
| 740 | '' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 741 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 742 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 743 | Indices may be negative numbers, to start counting from the right. |
| 744 | For example: |
| 745 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 746 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 747 | >>> word[-1] # The last character |
| 748 | 'A' |
| 749 | >>> word[-2] # The last-but-one character |
| 750 | 'p' |
| 751 | >>> word[-2:] # The last two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 752 | 'pA' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 753 | >>> word[:-2] # All but the last two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 754 | 'Hel' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 755 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 756 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 757 | But note that -0 is really the same as 0, so it does not count from |
| 758 | the right! |
| 759 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 760 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 761 | >>> word[-0] # (since -0 equals 0) |
| 762 | 'H' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 763 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 764 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 765 | Out-of-range negative slice indices are truncated, but don't try this |
| 766 | for single-element (non-slice) indices: |
| 767 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 768 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 769 | >>> word[-100:] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 770 | 'HelpA' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 771 | >>> word[-10] # error |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 772 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 773 | File "<stdin>", line 1, in ? |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 774 | IndexError: string index out of range |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 775 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 776 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 777 | The best way to remember how slices work is to think of the indices as |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 778 | pointing \emph{between} characters, with the left edge of the first |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 779 | character numbered 0. Then the right edge of the last character of a |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 780 | string of \var{n} characters has index \var{n}, for example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 781 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 782 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 783 | +---+---+---+---+---+ |
| 784 | | H | e | l | p | A | |
| 785 | +---+---+---+---+---+ |
| 786 | 0 1 2 3 4 5 |
| 787 | -5 -4 -3 -2 -1 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 788 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 789 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 790 | The first row of numbers gives the position of the indices 0...5 in |
| 791 | the string; the second row gives the corresponding negative indices. |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 792 | The slice from \var{i} to \var{j} consists of all characters between |
| 793 | the edges labeled \var{i} and \var{j}, respectively. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 794 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 795 | For non-negative indices, the length of a slice is the difference of |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 796 | the indices, if both are within bounds. For example, the length of |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 797 | \code{word[1:3]} is 2. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 798 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 799 | The built-in function \function{len()} returns the length of a string: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 800 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 801 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 802 | >>> s = 'supercalifragilisticexpialidocious' |
| 803 | >>> len(s) |
| 804 | 34 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 805 | \end{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 806 | |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 807 | |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 808 | \begin{seealso} |
| 809 | \seetitle[../lib/typesseq.html]{Sequence Types}% |
| 810 | {Strings, and the Unicode strings described in the next |
| 811 | section, are examples of \emph{sequence types}, and |
| 812 | support the common operations supported by such types.} |
| 813 | \seetitle[../lib/string-methods.html]{String Methods}% |
| 814 | {Both strings and Unicode strings support a large number of |
| 815 | methods for basic transformations and searching.} |
| 816 | \seetitle[../lib/typesseq-strings.html]{String Formatting Operations}% |
| 817 | {The formatting operations invoked when strings and Unicode |
| 818 | strings are the left operand of the \code{\%} operator are |
| 819 | described in more detail here.} |
| 820 | \end{seealso} |
| 821 | |
| 822 | |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 823 | \subsection{Unicode Strings \label{unicodeStrings}} |
| 824 | \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} |
| 825 | |
Fred Drake | 30f76ff | 2000-06-30 16:06:19 +0000 | [diff] [blame] | 826 | Starting with Python 2.0 a new data type for storing text data is |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 827 | available to the programmer: the Unicode object. It can be used to |
Fred Drake | 17f690f | 2001-07-14 02:14:42 +0000 | [diff] [blame] | 828 | store and manipulate Unicode data (see \url{http://www.unicode.org/}) |
Thomas Wouters | f9b526d | 2000-07-16 19:05:38 +0000 | [diff] [blame] | 829 | and integrates well with the existing string objects providing |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 830 | auto-conversions where necessary. |
| 831 | |
| 832 | Unicode has the advantage of providing one ordinal for every character |
| 833 | in every script used in modern and ancient texts. Previously, there |
| 834 | were only 256 possible ordinals for script characters and texts were |
| 835 | typically bound to a code page which mapped the ordinals to script |
| 836 | characters. This lead to very much confusion especially with respect |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 837 | to internationalization (usually written as \samp{i18n} --- |
| 838 | \character{i} + 18 characters + \character{n}) of software. Unicode |
| 839 | solves these problems by defining one code page for all scripts. |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 840 | |
| 841 | Creating Unicode strings in Python is just as simple as creating |
| 842 | normal strings: |
| 843 | |
| 844 | \begin{verbatim} |
| 845 | >>> u'Hello World !' |
| 846 | u'Hello World !' |
| 847 | \end{verbatim} |
| 848 | |
| 849 | The small \character{u} in front of the quote indicates that an |
| 850 | Unicode string is supposed to be created. If you want to include |
| 851 | special characters in the string, you can do so by using the Python |
| 852 | \emph{Unicode-Escape} encoding. The following example shows how: |
| 853 | |
| 854 | \begin{verbatim} |
Tim Peters | 657ebef | 2000-11-29 05:51:59 +0000 | [diff] [blame] | 855 | >>> u'Hello\u0020World !' |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 856 | u'Hello World !' |
| 857 | \end{verbatim} |
| 858 | |
Fred Drake | 4a6f1df | 2000-11-29 06:03:45 +0000 | [diff] [blame] | 859 | The escape sequence \code{\e u0020} indicates to insert the Unicode |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 860 | character with the ordinal value 0x0020 (the space character) at the |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 861 | given position. |
| 862 | |
| 863 | Other characters are interpreted by using their respective ordinal |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 864 | values directly as Unicode ordinals. If you have literal strings |
| 865 | in the standard Latin-1 encoding that is used in many Western countries, |
| 866 | you will find it convenient that the lower 256 characters |
| 867 | of Unicode are the same as the 256 characters of Latin-1. |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 868 | |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 869 | For experts, there is also a raw mode just like the one for normal |
| 870 | strings. You have to prefix the opening quote with 'ur' to have |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 871 | Python use the \emph{Raw-Unicode-Escape} encoding. It will only apply |
Fred Drake | 4a6f1df | 2000-11-29 06:03:45 +0000 | [diff] [blame] | 872 | the above \code{\e uXXXX} conversion if there is an uneven number of |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 873 | backslashes in front of the small 'u'. |
| 874 | |
| 875 | \begin{verbatim} |
| 876 | >>> ur'Hello\u0020World !' |
| 877 | u'Hello World !' |
| 878 | >>> ur'Hello\\u0020World !' |
| 879 | u'Hello\\\\u0020World !' |
| 880 | \end{verbatim} |
| 881 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 882 | The raw mode is most useful when you have to enter lots of |
| 883 | backslashes, as can be necessary in regular expressions. |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 884 | |
| 885 | Apart from these standard encodings, Python provides a whole set of |
Thomas Wouters | f9b526d | 2000-07-16 19:05:38 +0000 | [diff] [blame] | 886 | other ways of creating Unicode strings on the basis of a known |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 887 | encoding. |
| 888 | |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 889 | The built-in function \function{unicode()}\bifuncindex{unicode} provides |
| 890 | access to all registered Unicode codecs (COders and DECoders). Some of |
| 891 | the more well known encodings which these codecs can convert are |
| 892 | \emph{Latin-1}, \emph{ASCII}, \emph{UTF-8}, and \emph{UTF-16}. |
| 893 | The latter two are variable-length encodings that store each Unicode |
| 894 | character in one or more bytes. The default encoding is |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 895 | normally set to \ASCII, which passes through characters in the range |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 896 | 0 to 127 and rejects any other characters with an error. |
| 897 | When a Unicode string is printed, written to a file, or converted |
| 898 | with \function{str()}, conversion takes place using this default encoding. |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 899 | |
| 900 | \begin{verbatim} |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 901 | >>> u"abc" |
| 902 | u'abc' |
| 903 | >>> str(u"abc") |
| 904 | 'abc' |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 905 | >>> u"äöü" |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 906 | u'\xe4\xf6\xfc' |
| 907 | >>> str(u"äöü") |
| 908 | Traceback (most recent call last): |
| 909 | File "<stdin>", line 1, in ? |
Raymond Hettinger | a2f84ce | 2003-05-07 17:11:15 +0000 | [diff] [blame] | 910 | UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128) |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 911 | \end{verbatim} |
| 912 | |
| 913 | To convert a Unicode string into an 8-bit string using a specific |
| 914 | encoding, Unicode objects provide an \function{encode()} method |
| 915 | that takes one argument, the name of the encoding. Lowercase names |
| 916 | for encodings are preferred. |
| 917 | |
| 918 | \begin{verbatim} |
| 919 | >>> u"äöü".encode('utf-8') |
| 920 | '\xc3\xa4\xc3\xb6\xc3\xbc' |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 921 | \end{verbatim} |
| 922 | |
| 923 | If you have data in a specific encoding and want to produce a |
| 924 | corresponding Unicode string from it, you can use the |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 925 | \function{unicode()} function with the encoding name as the second |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 926 | argument. |
| 927 | |
| 928 | \begin{verbatim} |
Ka-Ping Yee | 5401996 | 2001-02-13 22:20:22 +0000 | [diff] [blame] | 929 | >>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8') |
| 930 | u'\xe4\xf6\xfc' |
Fred Drake | 9dc30bb | 2000-04-06 14:17:03 +0000 | [diff] [blame] | 931 | \end{verbatim} |
| 932 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 933 | \subsection{Lists \label{lists}} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 934 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 935 | Python knows a number of \emph{compound} data types, used to group |
| 936 | together other values. The most versatile is the \emph{list}, which |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 937 | can be written as a list of comma-separated values (items) between |
| 938 | square brackets. List items need not all have the same type. |
| 939 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 940 | \begin{verbatim} |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 941 | >>> a = ['spam', 'eggs', 100, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 942 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 943 | ['spam', 'eggs', 100, 1234] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 944 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 945 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 946 | Like string indices, list indices start at 0, and lists can be sliced, |
| 947 | concatenated and so on: |
| 948 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 949 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 950 | >>> a[0] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 951 | 'spam' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 952 | >>> a[3] |
| 953 | 1234 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 954 | >>> a[-2] |
| 955 | 100 |
| 956 | >>> a[1:-1] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 957 | ['eggs', 100] |
| 958 | >>> a[:2] + ['bacon', 2*2] |
| 959 | ['spam', 'eggs', 'bacon', 4] |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 960 | >>> 3*a[:3] + ['Boe!'] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 961 | ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 962 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 963 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 964 | Unlike strings, which are \emph{immutable}, it is possible to change |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 965 | individual elements of a list: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 966 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 967 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 968 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 969 | ['spam', 'eggs', 100, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 970 | >>> a[2] = a[2] + 23 |
| 971 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 972 | ['spam', 'eggs', 123, 1234] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 973 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 974 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 975 | Assignment to slices is also possible, and this can even change the size |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 976 | of the list: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 977 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 978 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 979 | >>> # Replace some items: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 980 | ... a[0:2] = [1, 12] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 981 | >>> a |
| 982 | [1, 12, 123, 1234] |
| 983 | >>> # Remove some: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 984 | ... a[0:2] = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 985 | >>> a |
| 986 | [123, 1234] |
| 987 | >>> # Insert some: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 988 | ... a[1:1] = ['bletch', 'xyzzy'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 989 | >>> a |
| 990 | [123, 'bletch', 'xyzzy', 1234] |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 991 | >>> a[:0] = a # Insert (a copy of) itself at the beginning |
| 992 | >>> a |
| 993 | [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 994 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 995 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 996 | The built-in function \function{len()} also applies to lists: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 997 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 998 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 999 | >>> len(a) |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1000 | 8 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1001 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1002 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1003 | It is possible to nest lists (create lists containing other lists), |
| 1004 | for example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1005 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1006 | \begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1007 | >>> q = [2, 3] |
| 1008 | >>> p = [1, q, 4] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1009 | >>> len(p) |
| 1010 | 3 |
| 1011 | >>> p[1] |
| 1012 | [2, 3] |
| 1013 | >>> p[1][0] |
| 1014 | 2 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1015 | >>> p[1].append('xtra') # See section 5.1 |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1016 | >>> p |
| 1017 | [1, [2, 3, 'xtra'], 4] |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1018 | >>> q |
| 1019 | [2, 3, 'xtra'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1020 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1021 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1022 | Note that in the last example, \code{p[1]} and \code{q} really refer to |
| 1023 | the same object! We'll come back to \emph{object semantics} later. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1024 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1025 | \section{First Steps Towards Programming \label{firstSteps}} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1026 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1027 | Of course, we can use Python for more complicated tasks than adding |
| 1028 | two and two together. For instance, we can write an initial |
Fred Drake | 979d041 | 2001-04-03 17:41:56 +0000 | [diff] [blame] | 1029 | sub-sequence of the \emph{Fibonacci} series as follows: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1030 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1031 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1032 | >>> # Fibonacci series: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1033 | ... # the sum of two elements defines the next |
| 1034 | ... a, b = 0, 1 |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1035 | >>> while b < 10: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1036 | ... print b |
| 1037 | ... a, b = b, a+b |
| 1038 | ... |
| 1039 | 1 |
| 1040 | 1 |
| 1041 | 2 |
| 1042 | 3 |
| 1043 | 5 |
| 1044 | 8 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1045 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1046 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1047 | This example introduces several new features. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1048 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1049 | \begin{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1050 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1051 | \item |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1052 | The first line contains a \emph{multiple assignment}: the variables |
| 1053 | \code{a} and \code{b} simultaneously get the new values 0 and 1. On the |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1054 | last line this is used again, demonstrating that the expressions on |
| 1055 | the right-hand side are all evaluated first before any of the |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1056 | assignments take place. The right-hand side expressions are evaluated |
| 1057 | from the left to the right. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1058 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1059 | \item |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1060 | The \keyword{while} loop executes as long as the condition (here: |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1061 | \code{b < 10}) remains true. In Python, like in C, any non-zero |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1062 | integer value is true; zero is false. The condition may also be a |
| 1063 | string or list value, in fact any sequence; anything with a non-zero |
| 1064 | length is true, empty sequences are false. The test used in the |
| 1065 | example is a simple comparison. The standard comparison operators are |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1066 | written the same as in C: \code{<} (less than), \code{>} (greater than), |
| 1067 | \code{==} (equal to), \code{<=} (less than or equal to), |
| 1068 | \code{>=} (greater than or equal to) and \code{!=} (not equal to). |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1069 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1070 | \item |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1071 | The \emph{body} of the loop is \emph{indented}: indentation is Python's |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1072 | way of grouping statements. Python does not (yet!) provide an |
| 1073 | intelligent input line editing facility, so you have to type a tab or |
| 1074 | space(s) for each indented line. In practice you will prepare more |
| 1075 | complicated input for Python with a text editor; most text editors have |
| 1076 | an auto-indent facility. When a compound statement is entered |
| 1077 | interactively, it must be followed by a blank line to indicate |
| 1078 | completion (since the parser cannot guess when you have typed the last |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1079 | line). Note that each line within a basic block must be indented by |
| 1080 | the same amount. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1081 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1082 | \item |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1083 | The \keyword{print} statement writes the value of the expression(s) it is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1084 | given. It differs from just writing the expression you want to write |
| 1085 | (as we did earlier in the calculator examples) in the way it handles |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1086 | multiple expressions and strings. Strings are printed without quotes, |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1087 | and a space is inserted between items, so you can format things nicely, |
| 1088 | like this: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1089 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1090 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1091 | >>> i = 256*256 |
| 1092 | >>> print 'The value of i is', i |
| 1093 | The value of i is 65536 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1094 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1095 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1096 | A trailing comma avoids the newline after the output: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1097 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1098 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1099 | >>> a, b = 0, 1 |
| 1100 | >>> while b < 1000: |
| 1101 | ... print b, |
| 1102 | ... a, b = b, a+b |
| 1103 | ... |
| 1104 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1105 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1106 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1107 | Note that the interpreter inserts a newline before it prints the next |
| 1108 | prompt if the last line was not completed. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1109 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1110 | \end{itemize} |
| 1111 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1112 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1113 | \chapter{More Control Flow Tools \label{moreControl}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1114 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1115 | Besides the \keyword{while} statement just introduced, Python knows |
| 1116 | the usual control flow statements known from other languages, with |
| 1117 | some twists. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1118 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1119 | \section{\keyword{if} Statements \label{if}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1120 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1121 | Perhaps the most well-known statement type is the |
| 1122 | \keyword{if} statement. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1123 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1124 | \begin{verbatim} |
Fred Drake | d3ba10f | 2001-08-14 19:55:42 +0000 | [diff] [blame] | 1125 | >>> x = int(raw_input("Please enter an integer: ")) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1126 | >>> if x < 0: |
| 1127 | ... x = 0 |
| 1128 | ... print 'Negative changed to zero' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1129 | ... elif x == 0: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1130 | ... print 'Zero' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1131 | ... elif x == 1: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1132 | ... print 'Single' |
| 1133 | ... else: |
| 1134 | ... print 'More' |
| 1135 | ... |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1136 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1137 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1138 | There can be zero or more \keyword{elif} parts, and the |
| 1139 | \keyword{else} part is optional. The keyword `\keyword{elif}' is |
| 1140 | short for `else if', and is useful to avoid excessive indentation. An |
| 1141 | \keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1142 | % Weird spacings happen here if the wrapping of the source text |
| 1143 | % gets changed in the wrong way. |
Fred Drake | 860106a | 2000-10-20 03:03:18 +0000 | [diff] [blame] | 1144 | is a substitute for the \keyword{switch} or |
| 1145 | \keyword{case} statements found in other languages. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1146 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1147 | |
| 1148 | \section{\keyword{for} Statements \label{for}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1149 | |
Fred Drake | f790b16 | 1998-11-30 20:37:24 +0000 | [diff] [blame] | 1150 | The \keyword{for}\stindex{for} statement in Python differs a bit from |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1151 | what you may be used to in C or Pascal. Rather than always |
Fred Drake | f790b16 | 1998-11-30 20:37:24 +0000 | [diff] [blame] | 1152 | iterating over an arithmetic progression of numbers (like in Pascal), |
| 1153 | or giving the user the ability to define both the iteration step and |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1154 | halting condition (as C), Python's |
| 1155 | \keyword{for}\stindex{for} statement iterates over the items of any |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1156 | sequence (a list or a string), in the order that they appear in |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1157 | the sequence. For example (no pun intended): |
Fred Drake | f790b16 | 1998-11-30 20:37:24 +0000 | [diff] [blame] | 1158 | % One suggestion was to give a real C example here, but that may only |
| 1159 | % serve to confuse non-C programmers. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1160 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1161 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1162 | >>> # Measure some strings: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1163 | ... a = ['cat', 'window', 'defenestrate'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1164 | >>> for x in a: |
| 1165 | ... print x, len(x) |
| 1166 | ... |
| 1167 | cat 3 |
| 1168 | window 6 |
| 1169 | defenestrate 12 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1170 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1171 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1172 | It is not safe to modify the sequence being iterated over in the loop |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1173 | (this can only happen for mutable sequence types, such as lists). If |
| 1174 | you need to modify the list you are iterating over (for example, to |
| 1175 | duplicate selected items) you must iterate over a copy. The slice |
| 1176 | notation makes this particularly convenient: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1177 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1178 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1179 | >>> for x in a[:]: # make a slice copy of the entire list |
| 1180 | ... if len(x) > 6: a.insert(0, x) |
| 1181 | ... |
| 1182 | >>> a |
| 1183 | ['defenestrate', 'cat', 'window', 'defenestrate'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1184 | \end{verbatim} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1185 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1186 | |
| 1187 | \section{The \function{range()} Function \label{range}} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1188 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1189 | If you do need to iterate over a sequence of numbers, the built-in |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1190 | function \function{range()} comes in handy. It generates lists |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1191 | containing arithmetic progressions: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1192 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1193 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1194 | >>> range(10) |
| 1195 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1196 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1197 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1198 | The given end point is never part of the generated list; |
| 1199 | \code{range(10)} generates a list of 10 values, exactly the legal |
| 1200 | indices for items of a sequence of length 10. It is possible to let |
| 1201 | the range start at another number, or to specify a different increment |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1202 | (even negative; sometimes this is called the `step'): |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1203 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1204 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1205 | >>> range(5, 10) |
| 1206 | [5, 6, 7, 8, 9] |
| 1207 | >>> range(0, 10, 3) |
| 1208 | [0, 3, 6, 9] |
| 1209 | >>> range(-10, -100, -30) |
| 1210 | [-10, -40, -70] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1211 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1212 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1213 | To iterate over the indices of a sequence, combine |
| 1214 | \function{range()} and \function{len()} as follows: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1215 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1216 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1217 | >>> a = ['Mary', 'had', 'a', 'little', 'lamb'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1218 | >>> for i in range(len(a)): |
| 1219 | ... print i, a[i] |
| 1220 | ... |
| 1221 | 0 Mary |
| 1222 | 1 had |
| 1223 | 2 a |
| 1224 | 3 little |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1225 | 4 lamb |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1226 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1227 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1228 | |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 1229 | \section{\keyword{break} and \keyword{continue} Statements, and |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1230 | \keyword{else} Clauses on Loops |
| 1231 | \label{break}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1232 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1233 | The \keyword{break} statement, like in C, breaks out of the smallest |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1234 | enclosing \keyword{for} or \keyword{while} loop. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1235 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1236 | The \keyword{continue} statement, also borrowed from C, continues |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1237 | with the next iteration of the loop. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1238 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1239 | Loop statements may have an \code{else} clause; it is executed when |
| 1240 | the loop terminates through exhaustion of the list (with |
| 1241 | \keyword{for}) or when the condition becomes false (with |
| 1242 | \keyword{while}), but not when the loop is terminated by a |
| 1243 | \keyword{break} statement. This is exemplified by the following loop, |
| 1244 | which searches for prime numbers: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1245 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1246 | \begin{verbatim} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1247 | >>> for n in range(2, 10): |
| 1248 | ... for x in range(2, n): |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1249 | ... if n % x == 0: |
Fred Drake | 236ffba | 2003-08-16 06:30:47 +0000 | [diff] [blame] | 1250 | ... print n, 'equals', x, '*', n/x |
| 1251 | ... break |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1252 | ... else: |
Fred Drake | 236ffba | 2003-08-16 06:30:47 +0000 | [diff] [blame] | 1253 | ... # loop fell through without finding a factor |
| 1254 | ... print n, 'is a prime number' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1255 | ... |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1256 | 2 is a prime number |
| 1257 | 3 is a prime number |
| 1258 | 4 equals 2 * 2 |
| 1259 | 5 is a prime number |
| 1260 | 6 equals 2 * 3 |
| 1261 | 7 is a prime number |
| 1262 | 8 equals 2 * 4 |
| 1263 | 9 equals 3 * 3 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1264 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1265 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1266 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1267 | \section{\keyword{pass} Statements \label{pass}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1268 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1269 | The \keyword{pass} statement does nothing. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1270 | It can be used when a statement is required syntactically but the |
| 1271 | program requires no action. |
| 1272 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1273 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1274 | \begin{verbatim} |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 1275 | >>> while True: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1276 | ... pass # Busy-wait for keyboard interrupt |
| 1277 | ... |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1278 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1279 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1280 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1281 | \section{Defining Functions \label{functions}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1282 | |
| 1283 | We can create a function that writes the Fibonacci series to an |
| 1284 | arbitrary boundary: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1285 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1286 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1287 | >>> def fib(n): # write Fibonacci series up to n |
Fred Drake | 23d45f4 | 2001-12-20 23:54:56 +0000 | [diff] [blame] | 1288 | ... """Print a Fibonacci series up to n.""" |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1289 | ... a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1290 | ... while b < n: |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1291 | ... print b, |
| 1292 | ... a, b = b, a+b |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1293 | ... |
| 1294 | >>> # Now call the function we just defined: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1295 | ... fib(2000) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1296 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1297 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1298 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1299 | The keyword \keyword{def} introduces a function \emph{definition}. It |
| 1300 | must be followed by the function name and the parenthesized list of |
| 1301 | formal parameters. The statements that form the body of the function |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1302 | start at the next line, and must be indented. The first statement of |
| 1303 | the function body can optionally be a string literal; this string |
| 1304 | literal is the function's \index{documentation strings}documentation |
| 1305 | string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation} |
| 1306 | |
| 1307 | There are tools which use docstrings to automatically produce online |
| 1308 | or printed documentation, or to let the user interactively browse |
| 1309 | through code; it's good practice to include docstrings in code that |
| 1310 | you write, so try to make a habit of it. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1311 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1312 | The \emph{execution} of a function introduces a new symbol table used |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1313 | for the local variables of the function. More precisely, all variable |
| 1314 | assignments in a function store the value in the local symbol table; |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1315 | whereas variable references first look in the local symbol table, then |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1316 | in the global symbol table, and then in the table of built-in names. |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1317 | Thus, global variables cannot be directly assigned a value within a |
| 1318 | function (unless named in a \keyword{global} statement), although |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1319 | they may be referenced. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1320 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1321 | The actual parameters (arguments) to a function call are introduced in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1322 | the local symbol table of the called function when it is called; thus, |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1323 | arguments are passed using \emph{call by value} (where the |
| 1324 | \emph{value} is always an object \emph{reference}, not the value of |
| 1325 | the object).\footnote{ |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1326 | Actually, \emph{call by object reference} would be a better |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1327 | description, since if a mutable object is passed, the caller |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1328 | will see any changes the callee makes to it (items |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1329 | inserted into a list). |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1330 | } When a function calls another function, a new local symbol table is |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1331 | created for that call. |
| 1332 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1333 | A function definition introduces the function name in the current |
| 1334 | symbol table. The value of the function name |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1335 | has a type that is recognized by the interpreter as a user-defined |
| 1336 | function. This value can be assigned to another name which can then |
| 1337 | also be used as a function. This serves as a general renaming |
| 1338 | mechanism: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1339 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1340 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1341 | >>> fib |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1342 | <function object at 10042ed0> |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1343 | >>> f = fib |
| 1344 | >>> f(100) |
| 1345 | 1 1 2 3 5 8 13 21 34 55 89 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1346 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1347 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1348 | You might object that \code{fib} is not a function but a procedure. In |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1349 | Python, like in C, procedures are just functions that don't return a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1350 | value. In fact, technically speaking, procedures do return a value, |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1351 | albeit a rather boring one. This value is called \code{None} (it's a |
| 1352 | built-in name). Writing the value \code{None} is normally suppressed by |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1353 | the interpreter if it would be the only value written. You can see it |
| 1354 | if you really want to: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1355 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1356 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1357 | >>> print fib(0) |
| 1358 | None |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1359 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1360 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1361 | It is simple to write a function that returns a list of the numbers of |
| 1362 | the Fibonacci series, instead of printing it: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1363 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1364 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1365 | >>> def fib2(n): # return Fibonacci series up to n |
Fred Drake | 23d45f4 | 2001-12-20 23:54:56 +0000 | [diff] [blame] | 1366 | ... """Return a list containing the Fibonacci series up to n.""" |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1367 | ... result = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1368 | ... a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1369 | ... while b < n: |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1370 | ... result.append(b) # see below |
| 1371 | ... a, b = b, a+b |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1372 | ... return result |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1373 | ... |
| 1374 | >>> f100 = fib2(100) # call it |
| 1375 | >>> f100 # write the result |
| 1376 | [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1377 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1378 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1379 | This example, as usual, demonstrates some new Python features: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1380 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1381 | \begin{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1382 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1383 | \item |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1384 | The \keyword{return} statement returns with a value from a function. |
Fred Drake | 0fe5af9 | 2001-01-19 22:34:59 +0000 | [diff] [blame] | 1385 | \keyword{return} without an expression argument returns \code{None}. |
| 1386 | Falling off the end of a procedure also returns \code{None}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1387 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1388 | \item |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1389 | The statement \code{result.append(b)} calls a \emph{method} of the list |
| 1390 | object \code{result}. A method is a function that `belongs' to an |
| 1391 | object and is named \code{obj.methodname}, where \code{obj} is some |
| 1392 | object (this may be an expression), and \code{methodname} is the name |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1393 | of a method that is defined by the object's type. Different types |
| 1394 | define different methods. Methods of different types may have the |
| 1395 | same name without causing ambiguity. (It is possible to define your |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1396 | own object types and methods, using \emph{classes}, as discussed later |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1397 | in this tutorial.) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1398 | The method \method{append()} shown in the example, is defined for |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1399 | list objects; it adds a new element at the end of the list. In this |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1400 | example it is equivalent to \samp{result = result + [b]}, but more |
| 1401 | efficient. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1402 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1403 | \end{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1404 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1405 | \section{More on Defining Functions \label{defining}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1406 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1407 | It is also possible to define functions with a variable number of |
| 1408 | arguments. There are three forms, which can be combined. |
| 1409 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1410 | \subsection{Default Argument Values \label{defaultArgs}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1411 | |
| 1412 | The most useful form is to specify a default value for one or more |
| 1413 | arguments. This creates a function that can be called with fewer |
Fred Drake | f0ae427 | 2004-02-24 16:13:36 +0000 | [diff] [blame] | 1414 | arguments than it is defined to allow. For example: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1415 | |
| 1416 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1417 | def ask_ok(prompt, retries=4, complaint='Yes or no, please!'): |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 1418 | while True: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1419 | ok = raw_input(prompt) |
Raymond Hettinger | 2569528 | 2003-12-02 07:38:30 +0000 | [diff] [blame] | 1420 | if ok in ('y', 'ye', 'yes'): return True |
| 1421 | if ok in ('n', 'no', 'nop', 'nope'): return False |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1422 | retries = retries - 1 |
| 1423 | if retries < 0: raise IOError, 'refusenik user' |
| 1424 | print complaint |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1425 | \end{verbatim} |
| 1426 | |
| 1427 | This function can be called either like this: |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1428 | \code{ask_ok('Do you really want to quit?')} or like this: |
| 1429 | \code{ask_ok('OK to overwrite the file?', 2)}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1430 | |
| 1431 | The default values are evaluated at the point of function definition |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1432 | in the \emph{defining} scope, so that |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1433 | |
| 1434 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1435 | i = 5 |
Fred Drake | 8b09f49 | 2001-09-06 18:21:30 +0000 | [diff] [blame] | 1436 | |
| 1437 | def f(arg=i): |
| 1438 | print arg |
| 1439 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1440 | i = 6 |
| 1441 | f() |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1442 | \end{verbatim} |
| 1443 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1444 | will print \code{5}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1445 | |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 1446 | \strong{Important warning:} The default value is evaluated only once. |
| 1447 | This makes a difference when the default is a mutable object such as a |
Fred Drake | 3a8fbe7 | 2003-06-18 17:14:29 +0000 | [diff] [blame] | 1448 | list, dictionary, or instances of most classes. For example, the |
| 1449 | following function accumulates the arguments passed to it on |
| 1450 | subsequent calls: |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 1451 | |
| 1452 | \begin{verbatim} |
Fred Drake | 8b09f49 | 2001-09-06 18:21:30 +0000 | [diff] [blame] | 1453 | def f(a, L=[]): |
| 1454 | L.append(a) |
| 1455 | return L |
| 1456 | |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 1457 | print f(1) |
| 1458 | print f(2) |
| 1459 | print f(3) |
| 1460 | \end{verbatim} |
| 1461 | |
| 1462 | This will print |
| 1463 | |
| 1464 | \begin{verbatim} |
| 1465 | [1] |
| 1466 | [1, 2] |
| 1467 | [1, 2, 3] |
| 1468 | \end{verbatim} |
| 1469 | |
| 1470 | If you don't want the default to be shared between subsequent calls, |
| 1471 | you can write the function like this instead: |
| 1472 | |
| 1473 | \begin{verbatim} |
Fred Drake | 8b09f49 | 2001-09-06 18:21:30 +0000 | [diff] [blame] | 1474 | def f(a, L=None): |
| 1475 | if L is None: |
| 1476 | L = [] |
| 1477 | L.append(a) |
| 1478 | return L |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 1479 | \end{verbatim} |
| 1480 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1481 | \subsection{Keyword Arguments \label{keywordArgs}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1482 | |
| 1483 | Functions can also be called using |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1484 | keyword arguments of the form \samp{\var{keyword} = \var{value}}. For |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1485 | instance, the following function: |
| 1486 | |
| 1487 | \begin{verbatim} |
| 1488 | def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'): |
| 1489 | print "-- This parrot wouldn't", action, |
| 1490 | print "if you put", voltage, "Volts through it." |
| 1491 | print "-- Lovely plumage, the", type |
| 1492 | print "-- It's", state, "!" |
| 1493 | \end{verbatim} |
| 1494 | |
| 1495 | could be called in any of the following ways: |
| 1496 | |
| 1497 | \begin{verbatim} |
| 1498 | parrot(1000) |
| 1499 | parrot(action = 'VOOOOOM', voltage = 1000000) |
| 1500 | parrot('a thousand', state = 'pushing up the daisies') |
| 1501 | parrot('a million', 'bereft of life', 'jump') |
| 1502 | \end{verbatim} |
| 1503 | |
| 1504 | but the following calls would all be invalid: |
| 1505 | |
| 1506 | \begin{verbatim} |
| 1507 | parrot() # required argument missing |
| 1508 | parrot(voltage=5.0, 'dead') # non-keyword argument following keyword |
| 1509 | parrot(110, voltage=220) # duplicate value for argument |
| 1510 | parrot(actor='John Cleese') # unknown keyword |
| 1511 | \end{verbatim} |
| 1512 | |
| 1513 | In general, an argument list must have any positional arguments |
| 1514 | followed by any keyword arguments, where the keywords must be chosen |
| 1515 | from the formal parameter names. It's not important whether a formal |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 1516 | parameter has a default value or not. No argument may receive a |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1517 | value more than once --- formal parameter names corresponding to |
| 1518 | positional arguments cannot be used as keywords in the same calls. |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 1519 | Here's an example that fails due to this restriction: |
| 1520 | |
| 1521 | \begin{verbatim} |
| 1522 | >>> def function(a): |
| 1523 | ... pass |
| 1524 | ... |
| 1525 | >>> function(0, a=0) |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 1526 | Traceback (most recent call last): |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 1527 | File "<stdin>", line 1, in ? |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 1528 | TypeError: function() got multiple values for keyword argument 'a' |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 1529 | \end{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1530 | |
| 1531 | When a final formal parameter of the form \code{**\var{name}} is |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 1532 | present, it receives a \ulink{dictionary}{../lib/typesmapping.html} containing all keyword arguments |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1533 | whose keyword doesn't correspond to a formal parameter. This may be |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1534 | combined with a formal parameter of the form |
| 1535 | \code{*\var{name}} (described in the next subsection) which receives a |
| 1536 | tuple containing the positional arguments beyond the formal parameter |
| 1537 | list. (\code{*\var{name}} must occur before \code{**\var{name}}.) |
| 1538 | For example, if we define a function like this: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1539 | |
| 1540 | \begin{verbatim} |
| 1541 | def cheeseshop(kind, *arguments, **keywords): |
| 1542 | print "-- Do you have any", kind, '?' |
| 1543 | print "-- I'm sorry, we're all out of", kind |
| 1544 | for arg in arguments: print arg |
| 1545 | print '-'*40 |
Fred Drake | c26467d | 2002-01-29 14:53:30 +0000 | [diff] [blame] | 1546 | keys = keywords.keys() |
| 1547 | keys.sort() |
| 1548 | for kw in keys: print kw, ':', keywords[kw] |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1549 | \end{verbatim} |
| 1550 | |
| 1551 | It could be called like this: |
| 1552 | |
| 1553 | \begin{verbatim} |
| 1554 | cheeseshop('Limburger', "It's very runny, sir.", |
| 1555 | "It's really very, VERY runny, sir.", |
| 1556 | client='John Cleese', |
| 1557 | shopkeeper='Michael Palin', |
| 1558 | sketch='Cheese Shop Sketch') |
| 1559 | \end{verbatim} |
| 1560 | |
| 1561 | and of course it would print: |
| 1562 | |
| 1563 | \begin{verbatim} |
| 1564 | -- Do you have any Limburger ? |
| 1565 | -- I'm sorry, we're all out of Limburger |
| 1566 | It's very runny, sir. |
| 1567 | It's really very, VERY runny, sir. |
| 1568 | ---------------------------------------- |
| 1569 | client : John Cleese |
| 1570 | shopkeeper : Michael Palin |
| 1571 | sketch : Cheese Shop Sketch |
| 1572 | \end{verbatim} |
| 1573 | |
Fred Drake | c26467d | 2002-01-29 14:53:30 +0000 | [diff] [blame] | 1574 | Note that the \method{sort()} method of the list of keyword argument |
| 1575 | names is called before printing the contents of the \code{keywords} |
| 1576 | dictionary; if this is not done, the order in which the arguments are |
| 1577 | printed is undefined. |
| 1578 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1579 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1580 | \subsection{Arbitrary Argument Lists \label{arbitraryArgs}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1581 | |
| 1582 | Finally, the least frequently used option is to specify that a |
| 1583 | function can be called with an arbitrary number of arguments. These |
| 1584 | arguments will be wrapped up in a tuple. Before the variable number |
| 1585 | of arguments, zero or more normal arguments may occur. |
| 1586 | |
| 1587 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1588 | def fprintf(file, format, *args): |
| 1589 | file.write(format % args) |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1590 | \end{verbatim} |
| 1591 | |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1592 | |
Raymond Hettinger | 0eec087 | 2003-08-08 23:32:46 +0000 | [diff] [blame] | 1593 | \subsection{Unpacking Argument Lists \label{unpacking-arguments}} |
| 1594 | |
| 1595 | The reverse situation occurs when the arguments are already in a list |
| 1596 | or tuple but need to be unpacked for a function call requiring separate |
| 1597 | positional arguments. For instance, the built-in \function{range()} |
| 1598 | function expects separate \var{start} and \var{stop} arguments. If they |
| 1599 | are not available separately, write the function call with the |
| 1600 | \code{*}-operator to unpack the arguments out of a list or tuple: |
| 1601 | |
| 1602 | \begin{verbatim} |
| 1603 | >>> range(3, 6) # normal call with separate arguments |
| 1604 | [3, 4, 5] |
| 1605 | >>> args = [3, 6] |
| 1606 | >>> range(*args) # call with arguments unpacked from a list |
| 1607 | [3, 4, 5] |
| 1608 | \end{verbatim} |
| 1609 | |
| 1610 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1611 | \subsection{Lambda Forms \label{lambda}} |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1612 | |
| 1613 | By popular demand, a few features commonly found in functional |
| 1614 | programming languages and Lisp have been added to Python. With the |
| 1615 | \keyword{lambda} keyword, small anonymous functions can be created. |
| 1616 | Here's a function that returns the sum of its two arguments: |
| 1617 | \samp{lambda a, b: a+b}. Lambda forms can be used wherever function |
| 1618 | objects are required. They are syntactically restricted to a single |
| 1619 | expression. Semantically, they are just syntactic sugar for a normal |
| 1620 | function definition. Like nested function definitions, lambda forms |
Fred Drake | fcf9468 | 2001-12-03 21:47:37 +0000 | [diff] [blame] | 1621 | can reference variables from the containing scope: |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1622 | |
| 1623 | \begin{verbatim} |
Tim Peters | c113465 | 2000-11-27 06:38:04 +0000 | [diff] [blame] | 1624 | >>> def make_incrementor(n): |
Fred Drake | fcf9468 | 2001-12-03 21:47:37 +0000 | [diff] [blame] | 1625 | ... return lambda x: x + n |
Tim Peters | c113465 | 2000-11-27 06:38:04 +0000 | [diff] [blame] | 1626 | ... |
| 1627 | >>> f = make_incrementor(42) |
| 1628 | >>> f(0) |
| 1629 | 42 |
| 1630 | >>> f(1) |
| 1631 | 43 |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1632 | \end{verbatim} |
| 1633 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1634 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1635 | \subsection{Documentation Strings \label{docstrings}} |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1636 | |
| 1637 | There are emerging conventions about the content and formatting of |
| 1638 | documentation strings. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1639 | \index{docstrings}\index{documentation strings} |
| 1640 | \index{strings, documentation} |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1641 | |
| 1642 | The first line should always be a short, concise summary of the |
| 1643 | object's purpose. For brevity, it should not explicitly state the |
| 1644 | object's name or type, since these are available by other means |
| 1645 | (except if the name happens to be a verb describing a function's |
| 1646 | operation). This line should begin with a capital letter and end with |
| 1647 | a period. |
| 1648 | |
| 1649 | If there are more lines in the documentation string, the second line |
| 1650 | should be blank, visually separating the summary from the rest of the |
Fred Drake | 4b1a07a | 1999-03-12 18:21:32 +0000 | [diff] [blame] | 1651 | description. The following lines should be one or more paragraphs |
| 1652 | describing the object's calling conventions, its side effects, etc. |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1653 | |
| 1654 | The Python parser does not strip indentation from multi-line string |
| 1655 | literals in Python, so tools that process documentation have to strip |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1656 | indentation if desired. This is done using the following convention. |
| 1657 | The first non-blank line \emph{after} the first line of the string |
| 1658 | determines the amount of indentation for the entire documentation |
| 1659 | string. (We can't use the first line since it is generally adjacent |
| 1660 | to the string's opening quotes so its indentation is not apparent in |
| 1661 | the string literal.) Whitespace ``equivalent'' to this indentation is |
| 1662 | then stripped from the start of all lines of the string. Lines that |
| 1663 | are indented less should not occur, but if they occur all their |
| 1664 | leading whitespace should be stripped. Equivalence of whitespace |
| 1665 | should be tested after expansion of tabs (to 8 spaces, normally). |
| 1666 | |
| 1667 | Here is an example of a multi-line docstring: |
| 1668 | |
| 1669 | \begin{verbatim} |
| 1670 | >>> def my_function(): |
| 1671 | ... """Do nothing, but document it. |
| 1672 | ... |
| 1673 | ... No, really, it doesn't do anything. |
| 1674 | ... """ |
| 1675 | ... pass |
| 1676 | ... |
| 1677 | >>> print my_function.__doc__ |
| 1678 | Do nothing, but document it. |
| 1679 | |
| 1680 | No, really, it doesn't do anything. |
| 1681 | |
| 1682 | \end{verbatim} |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 1683 | |
| 1684 | |
| 1685 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1686 | \chapter{Data Structures \label{structures}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1687 | |
| 1688 | This chapter describes some things you've learned about already in |
| 1689 | more detail, and adds some new things as well. |
| 1690 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1691 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1692 | \section{More on Lists \label{moreLists}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1693 | |
| 1694 | The list data type has some more methods. Here are all of the methods |
Fred Drake | ed68854 | 1998-02-11 22:29:17 +0000 | [diff] [blame] | 1695 | of list objects: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1696 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1697 | \begin{methoddesc}[list]{append}{x} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1698 | Add an item to the end of the list; |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1699 | equivalent to \code{a[len(a):] = [\var{x}]}. |
| 1700 | \end{methoddesc} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1701 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1702 | \begin{methoddesc}[list]{extend}{L} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1703 | Extend the list by appending all the items in the given list; |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1704 | equivalent to \code{a[len(a):] = \var{L}}. |
| 1705 | \end{methoddesc} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1706 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1707 | \begin{methoddesc}[list]{insert}{i, x} |
| 1708 | Insert an item at a given position. The first argument is the index |
| 1709 | of the element before which to insert, so \code{a.insert(0, \var{x})} |
| 1710 | inserts at the front of the list, and \code{a.insert(len(a), \var{x})} |
| 1711 | is equivalent to \code{a.append(\var{x})}. |
| 1712 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1713 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1714 | \begin{methoddesc}[list]{remove}{x} |
| 1715 | Remove the first item from the list whose value is \var{x}. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1716 | It is an error if there is no such item. |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1717 | \end{methoddesc} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1718 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1719 | \begin{methoddesc}[list]{pop}{\optional{i}} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1720 | Remove the item at the given position in the list, and return it. If |
| 1721 | no index is specified, \code{a.pop()} returns the last item in the |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1722 | list. The item is also removed from the list. (The square brackets |
| 1723 | around the \var{i} in the method signature denote that the parameter |
| 1724 | is optional, not that you should type square brackets at that |
| 1725 | position. You will see this notation frequently in the |
| 1726 | \citetitle[../lib/lib.html]{Python Library Reference}.) |
| 1727 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1728 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1729 | \begin{methoddesc}[list]{index}{x} |
| 1730 | Return the index in the list of the first item whose value is \var{x}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1731 | It is an error if there is no such item. |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1732 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1733 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1734 | \begin{methoddesc}[list]{count}{x} |
| 1735 | Return the number of times \var{x} appears in the list. |
| 1736 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1737 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1738 | \begin{methoddesc}[list]{sort}{} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1739 | Sort the items of the list, in place. |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1740 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1741 | |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1742 | \begin{methoddesc}[list]{reverse}{} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1743 | Reverse the elements of the list, in place. |
Fred Drake | 55ad7f8 | 2002-06-11 02:56:17 +0000 | [diff] [blame] | 1744 | \end{methoddesc} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1745 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1746 | An example that uses most of the list methods: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1747 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1748 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1749 | >>> a = [66.6, 333, 333, 1, 1234.5] |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1750 | >>> print a.count(333), a.count(66.6), a.count('x') |
| 1751 | 2 1 0 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1752 | >>> a.insert(2, -1) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1753 | >>> a.append(333) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1754 | >>> a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1755 | [66.6, 333, -1, 333, 1, 1234.5, 333] |
| 1756 | >>> a.index(333) |
| 1757 | 1 |
| 1758 | >>> a.remove(333) |
| 1759 | >>> a |
| 1760 | [66.6, -1, 333, 1, 1234.5, 333] |
| 1761 | >>> a.reverse() |
| 1762 | >>> a |
| 1763 | [333, 1234.5, 1, 333, -1, 66.6] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1764 | >>> a.sort() |
| 1765 | >>> a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1766 | [-1, 1, 66.6, 333, 333, 1234.5] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1767 | \end{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1768 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1769 | |
| 1770 | \subsection{Using Lists as Stacks \label{lists-as-stacks}} |
Fred Drake | 67fdaa4 | 2001-03-06 07:19:34 +0000 | [diff] [blame] | 1771 | \sectionauthor{Ka-Ping Yee}{ping@lfw.org} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1772 | |
| 1773 | The list methods make it very easy to use a list as a stack, where the |
| 1774 | last element added is the first element retrieved (``last-in, |
| 1775 | first-out''). To add an item to the top of the stack, use |
| 1776 | \method{append()}. To retrieve an item from the top of the stack, use |
| 1777 | \method{pop()} without an explicit index. For example: |
| 1778 | |
| 1779 | \begin{verbatim} |
| 1780 | >>> stack = [3, 4, 5] |
| 1781 | >>> stack.append(6) |
| 1782 | >>> stack.append(7) |
| 1783 | >>> stack |
| 1784 | [3, 4, 5, 6, 7] |
| 1785 | >>> stack.pop() |
| 1786 | 7 |
| 1787 | >>> stack |
| 1788 | [3, 4, 5, 6] |
| 1789 | >>> stack.pop() |
| 1790 | 6 |
| 1791 | >>> stack.pop() |
| 1792 | 5 |
| 1793 | >>> stack |
| 1794 | [3, 4] |
| 1795 | \end{verbatim} |
| 1796 | |
| 1797 | |
| 1798 | \subsection{Using Lists as Queues \label{lists-as-queues}} |
Fred Drake | 67fdaa4 | 2001-03-06 07:19:34 +0000 | [diff] [blame] | 1799 | \sectionauthor{Ka-Ping Yee}{ping@lfw.org} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 1800 | |
| 1801 | You can also use a list conveniently as a queue, where the first |
| 1802 | element added is the first element retrieved (``first-in, |
| 1803 | first-out''). To add an item to the back of the queue, use |
| 1804 | \method{append()}. To retrieve an item from the front of the queue, |
| 1805 | use \method{pop()} with \code{0} as the index. For example: |
| 1806 | |
| 1807 | \begin{verbatim} |
| 1808 | >>> queue = ["Eric", "John", "Michael"] |
| 1809 | >>> queue.append("Terry") # Terry arrives |
| 1810 | >>> queue.append("Graham") # Graham arrives |
| 1811 | >>> queue.pop(0) |
| 1812 | 'Eric' |
| 1813 | >>> queue.pop(0) |
| 1814 | 'John' |
| 1815 | >>> queue |
| 1816 | ['Michael', 'Terry', 'Graham'] |
| 1817 | \end{verbatim} |
| 1818 | |
| 1819 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1820 | \subsection{Functional Programming Tools \label{functional}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1821 | |
| 1822 | There are three built-in functions that are very useful when used with |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1823 | lists: \function{filter()}, \function{map()}, and \function{reduce()}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1824 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1825 | \samp{filter(\var{function}, \var{sequence})} returns a sequence (of |
| 1826 | the same type, if possible) consisting of those items from the |
| 1827 | sequence for which \code{\var{function}(\var{item})} is true. For |
| 1828 | example, to compute some primes: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1829 | |
| 1830 | \begin{verbatim} |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 1831 | >>> def f(x): return x % 2 != 0 and x % 3 != 0 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1832 | ... |
| 1833 | >>> filter(f, range(2, 25)) |
| 1834 | [5, 7, 11, 13, 17, 19, 23] |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1835 | \end{verbatim} |
| 1836 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1837 | \samp{map(\var{function}, \var{sequence})} calls |
| 1838 | \code{\var{function}(\var{item})} for each of the sequence's items and |
| 1839 | returns a list of the return values. For example, to compute some |
| 1840 | cubes: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1841 | |
| 1842 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1843 | >>> def cube(x): return x*x*x |
| 1844 | ... |
| 1845 | >>> map(cube, range(1, 11)) |
| 1846 | [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000] |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1847 | \end{verbatim} |
| 1848 | |
| 1849 | More than one sequence may be passed; the function must then have as |
| 1850 | many arguments as there are sequences and is called with the |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1851 | corresponding item from each sequence (or \code{None} if some sequence |
Neil Schemenauer | 90b182c | 2003-08-14 22:57:46 +0000 | [diff] [blame] | 1852 | is shorter than another). For example: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1853 | |
| 1854 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1855 | >>> seq = range(8) |
Neil Schemenauer | 90b182c | 2003-08-14 22:57:46 +0000 | [diff] [blame] | 1856 | >>> def add(x, y): return x+y |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1857 | ... |
Neil Schemenauer | 90b182c | 2003-08-14 22:57:46 +0000 | [diff] [blame] | 1858 | >>> map(add, seq, seq) |
| 1859 | [0, 2, 4, 6, 8, 10, 12, 14] |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1860 | \end{verbatim} |
| 1861 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1862 | \samp{reduce(\var{func}, \var{sequence})} returns a single value |
| 1863 | constructed by calling the binary function \var{func} on the first two |
| 1864 | items of the sequence, then on the result and the next item, and so |
| 1865 | on. For example, to compute the sum of the numbers 1 through 10: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1866 | |
| 1867 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1868 | >>> def add(x,y): return x+y |
| 1869 | ... |
| 1870 | >>> reduce(add, range(1, 11)) |
| 1871 | 55 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1872 | \end{verbatim} |
| 1873 | |
| 1874 | If there's only one item in the sequence, its value is returned; if |
| 1875 | the sequence is empty, an exception is raised. |
| 1876 | |
| 1877 | A third argument can be passed to indicate the starting value. In this |
| 1878 | case the starting value is returned for an empty sequence, and the |
| 1879 | function is first applied to the starting value and the first sequence |
| 1880 | item, then to the result and the next item, and so on. For example, |
| 1881 | |
| 1882 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1883 | >>> def sum(seq): |
| 1884 | ... def add(x,y): return x+y |
| 1885 | ... return reduce(add, seq, 0) |
| 1886 | ... |
| 1887 | >>> sum(range(1, 11)) |
| 1888 | 55 |
| 1889 | >>> sum([]) |
| 1890 | 0 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 1891 | \end{verbatim} |
| 1892 | |
Fred Drake | 03e929e | 2003-04-22 14:30:53 +0000 | [diff] [blame] | 1893 | Don't use this example's definition of \function{sum()}: since summing |
| 1894 | numbers is such a common need, a built-in function |
| 1895 | \code{sum(\var{sequence})} is already provided, and works exactly like |
| 1896 | this. |
| 1897 | \versionadded{2.3} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1898 | |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1899 | \subsection{List Comprehensions} |
| 1900 | |
Skip Montanaro | 46dfa5f | 2000-08-22 02:43:07 +0000 | [diff] [blame] | 1901 | List comprehensions provide a concise way to create lists without resorting |
| 1902 | to use of \function{map()}, \function{filter()} and/or \keyword{lambda}. |
| 1903 | The resulting list definition tends often to be clearer than lists built |
| 1904 | using those constructs. Each list comprehension consists of an expression |
Fred Drake | 33fd5f7 | 2002-06-26 21:25:15 +0000 | [diff] [blame] | 1905 | followed by a \keyword{for} clause, then zero or more \keyword{for} or |
Skip Montanaro | 46dfa5f | 2000-08-22 02:43:07 +0000 | [diff] [blame] | 1906 | \keyword{if} clauses. The result will be a list resulting from evaluating |
| 1907 | the expression in the context of the \keyword{for} and \keyword{if} clauses |
| 1908 | which follow it. If the expression would evaluate to a tuple, it must be |
| 1909 | parenthesized. |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1910 | |
| 1911 | \begin{verbatim} |
Fred Drake | 1aebadf | 2000-08-16 21:44:03 +0000 | [diff] [blame] | 1912 | >>> freshfruit = [' banana', ' loganberry ', 'passion fruit '] |
| 1913 | >>> [weapon.strip() for weapon in freshfruit] |
| 1914 | ['banana', 'loganberry', 'passion fruit'] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1915 | >>> vec = [2, 4, 6] |
Fred Drake | 1aebadf | 2000-08-16 21:44:03 +0000 | [diff] [blame] | 1916 | >>> [3*x for x in vec] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1917 | [6, 12, 18] |
Fred Drake | 1aebadf | 2000-08-16 21:44:03 +0000 | [diff] [blame] | 1918 | >>> [3*x for x in vec if x > 3] |
| 1919 | [12, 18] |
| 1920 | >>> [3*x for x in vec if x < 2] |
| 1921 | [] |
Skip Montanaro | 46dfa5f | 2000-08-22 02:43:07 +0000 | [diff] [blame] | 1922 | >>> [[x,x**2] for x in vec] |
| 1923 | [[2, 4], [4, 16], [6, 36]] |
| 1924 | >>> [x, x**2 for x in vec] # error - parens required for tuples |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 1925 | File "<stdin>", line 1, in ? |
Skip Montanaro | 46dfa5f | 2000-08-22 02:43:07 +0000 | [diff] [blame] | 1926 | [x, x**2 for x in vec] |
| 1927 | ^ |
| 1928 | SyntaxError: invalid syntax |
| 1929 | >>> [(x, x**2) for x in vec] |
| 1930 | [(2, 4), (4, 16), (6, 36)] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1931 | >>> vec1 = [2, 4, 6] |
| 1932 | >>> vec2 = [4, 3, -9] |
Fred Drake | 1aebadf | 2000-08-16 21:44:03 +0000 | [diff] [blame] | 1933 | >>> [x*y for x in vec1 for y in vec2] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1934 | [8, 6, -18, 16, 12, -36, 24, 18, -54] |
Fred Drake | 1aebadf | 2000-08-16 21:44:03 +0000 | [diff] [blame] | 1935 | >>> [x+y for x in vec1 for y in vec2] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1936 | [6, 5, -7, 8, 7, -5, 10, 9, -3] |
Fred Drake | 1da50f6 | 2001-12-03 18:54:33 +0000 | [diff] [blame] | 1937 | >>> [vec1[i]*vec2[i] for i in range(len(vec1))] |
| 1938 | [8, 12, -54] |
Skip Montanaro | 803d6e5 | 2000-08-12 18:09:51 +0000 | [diff] [blame] | 1939 | \end{verbatim} |
| 1940 | |
Raymond Hettinger | 57d7128 | 2003-08-30 23:21:32 +0000 | [diff] [blame] | 1941 | List comprehensions are much more flexible than \function{map()} and can be |
| 1942 | applied to functions with more than one argument and to nested functions: |
| 1943 | |
| 1944 | \begin{verbatim} |
| 1945 | >>> [str(round(355/113.0, i)) for i in range(1,6)] |
| 1946 | ['3.1', '3.14', '3.142', '3.1416', '3.14159'] |
| 1947 | \end{verbatim} |
| 1948 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1949 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1950 | \section{The \keyword{del} statement \label{del}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1951 | |
| 1952 | There is a way to remove an item from a list given its index instead |
Fred Drake | 81f7eb6 | 2000-08-12 20:08:04 +0000 | [diff] [blame] | 1953 | of its value: the \keyword{del} statement. This can also be used to |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1954 | remove slices from a list (which we did earlier by assignment of an |
| 1955 | empty list to the slice). For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1956 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1957 | \begin{verbatim} |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 1958 | >>> a = [-1, 1, 66.6, 333, 333, 1234.5] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1959 | >>> del a[0] |
| 1960 | >>> a |
| 1961 | [1, 66.6, 333, 333, 1234.5] |
| 1962 | >>> del a[2:4] |
| 1963 | >>> a |
| 1964 | [1, 66.6, 1234.5] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1965 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1966 | |
| 1967 | \keyword{del} can also be used to delete entire variables: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1968 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1969 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1970 | >>> del a |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1971 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1972 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1973 | Referencing the name \code{a} hereafter is an error (at least until |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 1974 | another value is assigned to it). We'll find other uses for |
| 1975 | \keyword{del} later. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1976 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 1977 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 1978 | \section{Tuples and Sequences \label{tuples}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1979 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 1980 | We saw that lists and strings have many common properties, such as |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 1981 | indexing and slicing operations. They are two examples of |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 1982 | \ulink{\emph{sequence} data types}{../lib/typesseq.html}. Since |
| 1983 | Python is an evolving language, other sequence data types may be |
| 1984 | added. There is also another standard sequence data type: the |
| 1985 | \emph{tuple}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1986 | |
| 1987 | A tuple consists of a number of values separated by commas, for |
| 1988 | instance: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1989 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 1990 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1991 | >>> t = 12345, 54321, 'hello!' |
| 1992 | >>> t[0] |
| 1993 | 12345 |
| 1994 | >>> t |
| 1995 | (12345, 54321, 'hello!') |
| 1996 | >>> # Tuples may be nested: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1997 | ... u = t, (1, 2, 3, 4, 5) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1998 | >>> u |
| 1999 | ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5)) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2000 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2001 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2002 | As you see, on output tuples are alway enclosed in parentheses, so |
| 2003 | that nested tuples are interpreted correctly; they may be input with |
| 2004 | or without surrounding parentheses, although often parentheses are |
| 2005 | necessary anyway (if the tuple is part of a larger expression). |
| 2006 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2007 | Tuples have many uses. For example: (x, y) coordinate pairs, employee |
| 2008 | records from a database, etc. Tuples, like strings, are immutable: it |
| 2009 | is not possible to assign to the individual items of a tuple (you can |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2010 | simulate much of the same effect with slicing and concatenation, |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2011 | though). It is also possible to create tuples which contain mutable |
| 2012 | objects, such as lists. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2013 | |
| 2014 | A special problem is the construction of tuples containing 0 or 1 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2015 | items: the syntax has some extra quirks to accommodate these. Empty |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2016 | tuples are constructed by an empty pair of parentheses; a tuple with |
| 2017 | one item is constructed by following a value with a comma |
| 2018 | (it is not sufficient to enclose a single value in parentheses). |
| 2019 | Ugly, but effective. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2020 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2021 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2022 | >>> empty = () |
| 2023 | >>> singleton = 'hello', # <-- note trailing comma |
| 2024 | >>> len(empty) |
| 2025 | 0 |
| 2026 | >>> len(singleton) |
| 2027 | 1 |
| 2028 | >>> singleton |
| 2029 | ('hello',) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2030 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2031 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2032 | The statement \code{t = 12345, 54321, 'hello!'} is an example of |
| 2033 | \emph{tuple packing}: the values \code{12345}, \code{54321} and |
| 2034 | \code{'hello!'} are packed together in a tuple. The reverse operation |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2035 | is also possible: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2036 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2037 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2038 | >>> x, y, z = t |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2039 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2040 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2041 | This is called, appropriately enough, \emph{sequence unpacking}. |
| 2042 | Sequence unpacking requires that the list of variables on the left |
| 2043 | have the same number of elements as the length of the sequence. Note |
| 2044 | that multiple assignment is really just a combination of tuple packing |
| 2045 | and sequence unpacking! |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2046 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2047 | There is a small bit of asymmetry here: packing multiple values |
| 2048 | always creates a tuple, and unpacking works for any sequence. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2049 | |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 2050 | % XXX Add a bit on the difference between tuples and lists. |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2051 | |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 2052 | |
Raymond Hettinger | 65674b8 | 2003-11-18 17:50:34 +0000 | [diff] [blame] | 2053 | \section{Sets \label{sets}} |
| 2054 | |
| 2055 | Python also includes a data type for \emph{sets}. A set is an unordered |
| 2056 | collection with no duplicate elements. Basic uses include membership |
| 2057 | testing and eliminating duplicate entries. Set objects also support |
| 2058 | mathematical operations like union, intersection, difference, and |
| 2059 | symmetric difference. |
| 2060 | |
| 2061 | Here is a brief demonstration: |
| 2062 | |
| 2063 | \begin{verbatim} |
| 2064 | >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana'] |
| 2065 | >>> fruits = set(basket) # create a set without duplicates |
| 2066 | >>> fruits |
| 2067 | set(['orange', 'pear', 'apple', 'banana']) |
| 2068 | >>> 'orange' in fruits # fast membership testing |
| 2069 | True |
| 2070 | >>> 'crabgrass' in fruits |
| 2071 | False |
| 2072 | |
| 2073 | >>> # Demonstrate set operations on unique letters from two words |
| 2074 | ... |
| 2075 | >>> a = set('abracadabra') |
| 2076 | >>> b = set('alacazam') |
| 2077 | >>> a # unique letters in a |
| 2078 | set(['a', 'r', 'b', 'c', 'd']) |
| 2079 | >>> a - b # letters in a but not in b |
| 2080 | set(['r', 'd', 'b']) |
| 2081 | >>> a | b # letters in either a or b |
| 2082 | set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l']) |
| 2083 | >>> a & b # letters in both a and b |
| 2084 | set(['a', 'c']) |
| 2085 | >>> a ^ b # letters in a or b but not both |
| 2086 | set(['r', 'd', 'b', 'm', 'z', 'l']) |
| 2087 | \end{verbatim} |
| 2088 | |
| 2089 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2090 | \section{Dictionaries \label{dictionaries}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2091 | |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2092 | Another useful data type built into Python is the |
| 2093 | \ulink{\emph{dictionary}}{../lib/typesmapping.html}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2094 | Dictionaries are sometimes found in other languages as ``associative |
| 2095 | memories'' or ``associative arrays''. Unlike sequences, which are |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2096 | indexed by a range of numbers, dictionaries are indexed by \emph{keys}, |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 2097 | which can be any immutable type; strings and numbers can always be |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2098 | keys. Tuples can be used as keys if they contain only strings, |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2099 | numbers, or tuples; if a tuple contains any mutable object either |
| 2100 | directly or indirectly, it cannot be used as a key. You can't use |
| 2101 | lists as keys, since lists can be modified in place using their |
| 2102 | \method{append()} and \method{extend()} methods, as well as slice and |
| 2103 | indexed assignments. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2104 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2105 | It is best to think of a dictionary as an unordered set of |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2106 | \emph{key: value} pairs, with the requirement that the keys are unique |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2107 | (within one dictionary). |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2108 | A pair of braces creates an empty dictionary: \code{\{\}}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2109 | Placing a comma-separated list of key:value pairs within the |
| 2110 | braces adds initial key:value pairs to the dictionary; this is also the |
| 2111 | way dictionaries are written on output. |
| 2112 | |
| 2113 | The main operations on a dictionary are storing a value with some key |
| 2114 | and extracting the value given the key. It is also possible to delete |
| 2115 | a key:value pair |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2116 | with \code{del}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2117 | If you store using a key that is already in use, the old value |
| 2118 | associated with that key is forgotten. It is an error to extract a |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2119 | value using a non-existent key. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2120 | |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2121 | The \method{keys()} method of a dictionary object returns a list of all |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2122 | the keys used in the dictionary, in random order (if you want it |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2123 | sorted, just apply the \method{sort()} method to the list of keys). To |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2124 | check whether a single key is in the dictionary, use the |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2125 | \method{has_key()} method of the dictionary. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2126 | |
| 2127 | Here is a small example using a dictionary: |
| 2128 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2129 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2130 | >>> tel = {'jack': 4098, 'sape': 4139} |
| 2131 | >>> tel['guido'] = 4127 |
| 2132 | >>> tel |
Guido van Rossum | 8f96f77 | 1991-11-12 15:45:03 +0000 | [diff] [blame] | 2133 | {'sape': 4139, 'guido': 4127, 'jack': 4098} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2134 | >>> tel['jack'] |
| 2135 | 4098 |
| 2136 | >>> del tel['sape'] |
| 2137 | >>> tel['irv'] = 4127 |
| 2138 | >>> tel |
Guido van Rossum | 8f96f77 | 1991-11-12 15:45:03 +0000 | [diff] [blame] | 2139 | {'guido': 4127, 'irv': 4127, 'jack': 4098} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2140 | >>> tel.keys() |
| 2141 | ['guido', 'irv', 'jack'] |
| 2142 | >>> tel.has_key('guido') |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 2143 | True |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2144 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2145 | |
Walter Dörwald | 7bafa9f | 2003-12-03 10:34:57 +0000 | [diff] [blame] | 2146 | The \function{dict()} constructor builds dictionaries directly from |
Raymond Hettinger | 07dc918 | 2002-06-25 15:13:18 +0000 | [diff] [blame] | 2147 | lists of key-value pairs stored as tuples. When the pairs form a |
| 2148 | pattern, list comprehensions can compactly specify the key-value list. |
| 2149 | |
| 2150 | \begin{verbatim} |
| 2151 | >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)]) |
| 2152 | {'sape': 4139, 'jack': 4098, 'guido': 4127} |
| 2153 | >>> dict([(x, x**2) for x in vec]) # use a list comprehension |
| 2154 | {2: 4, 4: 16, 6: 36} |
| 2155 | \end{verbatim} |
| 2156 | |
Fred Drake | 38f7197 | 2002-04-26 20:29:44 +0000 | [diff] [blame] | 2157 | |
| 2158 | \section{Looping Techniques \label{loopidioms}} |
| 2159 | |
| 2160 | When looping through dictionaries, the key and corresponding value can |
Raymond Hettinger | d446230 | 2003-11-26 17:52:45 +0000 | [diff] [blame] | 2161 | be retrieved at the same time using the \method{iteritems()} method. |
Fred Drake | 38f7197 | 2002-04-26 20:29:44 +0000 | [diff] [blame] | 2162 | |
| 2163 | \begin{verbatim} |
| 2164 | >>> knights = {'gallahad': 'the pure', 'robin': 'the brave'} |
Raymond Hettinger | d446230 | 2003-11-26 17:52:45 +0000 | [diff] [blame] | 2165 | >>> for k, v in knights.iteritems(): |
Fred Drake | 38f7197 | 2002-04-26 20:29:44 +0000 | [diff] [blame] | 2166 | ... print k, v |
| 2167 | ... |
| 2168 | gallahad the pure |
| 2169 | robin the brave |
| 2170 | \end{verbatim} |
| 2171 | |
| 2172 | When looping through a sequence, the position index and corresponding |
| 2173 | value can be retrieved at the same time using the |
| 2174 | \function{enumerate()} function. |
| 2175 | |
| 2176 | \begin{verbatim} |
| 2177 | >>> for i, v in enumerate(['tic', 'tac', 'toe']): |
| 2178 | ... print i, v |
| 2179 | ... |
| 2180 | 0 tic |
| 2181 | 1 tac |
| 2182 | 2 toe |
| 2183 | \end{verbatim} |
| 2184 | |
| 2185 | To loop over two or more sequences at the same time, the entries |
| 2186 | can be paired with the \function{zip()} function. |
| 2187 | |
| 2188 | \begin{verbatim} |
| 2189 | >>> questions = ['name', 'quest', 'favorite color'] |
| 2190 | >>> answers = ['lancelot', 'the holy grail', 'blue'] |
| 2191 | >>> for q, a in zip(questions, answers): |
| 2192 | ... print 'What is your %s? It is %s.' % (q, a) |
| 2193 | ... |
Raymond Hettinger | 7951f60 | 2002-06-25 03:17:03 +0000 | [diff] [blame] | 2194 | What is your name? It is lancelot. |
| 2195 | What is your quest? It is the holy grail. |
| 2196 | What is your favorite color? It is blue. |
Fred Drake | 38f7197 | 2002-04-26 20:29:44 +0000 | [diff] [blame] | 2197 | \end{verbatim} |
| 2198 | |
Raymond Hettinger | dc62aec | 2003-11-07 01:30:58 +0000 | [diff] [blame] | 2199 | To loop over a sequence in reverse, first specify the sequence |
| 2200 | in a forward direction and then call the \function{reversed()} |
| 2201 | function. |
| 2202 | |
| 2203 | \begin{verbatim} |
| 2204 | >>> for i in reversed(xrange(1,10,2)): |
| 2205 | ... print i |
| 2206 | ... |
| 2207 | 9 |
| 2208 | 7 |
| 2209 | 5 |
| 2210 | 3 |
| 2211 | 1 |
| 2212 | \end{verbatim} |
| 2213 | |
Raymond Hettinger | a95e87a | 2003-12-17 21:38:26 +0000 | [diff] [blame] | 2214 | To loop over a sequence in sorted order, use the \function{sorted()} |
| 2215 | function which returns a new sorted list while leaving the source |
| 2216 | unaltered. |
| 2217 | |
| 2218 | \begin{verbatim} |
| 2219 | >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana'] |
| 2220 | >>> for f in sorted(set(basket)): |
| 2221 | ... print f |
| 2222 | ... |
| 2223 | apple |
| 2224 | banana |
| 2225 | orange |
| 2226 | pear |
| 2227 | \end{verbatim} |
Fred Drake | 38f7197 | 2002-04-26 20:29:44 +0000 | [diff] [blame] | 2228 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2229 | \section{More on Conditions \label{conditions}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2230 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2231 | The conditions used in \code{while} and \code{if} statements above can |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2232 | contain other operators besides comparisons. |
| 2233 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2234 | The comparison operators \code{in} and \code{not in} check whether a value |
| 2235 | occurs (does not occur) in a sequence. The operators \code{is} and |
| 2236 | \code{is not} compare whether two objects are really the same object; this |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2237 | only matters for mutable objects like lists. All comparison operators |
| 2238 | have the same priority, which is lower than that of all numerical |
| 2239 | operators. |
| 2240 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2241 | Comparisons can be chained. For example, \code{a < b == c} tests |
| 2242 | whether \code{a} is less than \code{b} and moreover \code{b} equals |
| 2243 | \code{c}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2244 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2245 | Comparisons may be combined by the Boolean operators \code{and} and |
| 2246 | \code{or}, and the outcome of a comparison (or of any other Boolean |
| 2247 | expression) may be negated with \code{not}. These all have lower |
| 2248 | priorities than comparison operators again; between them, \code{not} has |
| 2249 | the highest priority, and \code{or} the lowest, so that |
| 2250 | \code{A and not B or C} is equivalent to \code{(A and (not B)) or C}. Of |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2251 | course, parentheses can be used to express the desired composition. |
| 2252 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2253 | The Boolean operators \code{and} and \code{or} are so-called |
Fred Drake | 6cb64f9 | 2002-03-08 00:54:43 +0000 | [diff] [blame] | 2254 | \emph{short-circuit} operators: their arguments are evaluated from |
| 2255 | left to right, and evaluation stops as soon as the outcome is |
| 2256 | determined. For example, if \code{A} and \code{C} are true but |
| 2257 | \code{B} is false, \code{A and B and C} does not evaluate the |
| 2258 | expression \code{C}. In general, the return value of a short-circuit |
| 2259 | operator, when used as a general value and not as a Boolean, is the |
| 2260 | last evaluated argument. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2261 | |
| 2262 | It is possible to assign the result of a comparison or other Boolean |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2263 | expression to a variable. For example, |
| 2264 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2265 | \begin{verbatim} |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2266 | >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance' |
| 2267 | >>> non_null = string1 or string2 or string3 |
| 2268 | >>> non_null |
| 2269 | 'Trondheim' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2270 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2271 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 2272 | Note that in Python, unlike C, assignment cannot occur inside expressions. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2273 | C programmers may grumble about this, but it avoids a common class of |
| 2274 | problems encountered in C programs: typing \code{=} in an expression when |
| 2275 | \code{==} was intended. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2276 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2277 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2278 | \section{Comparing Sequences and Other Types \label{comparing}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2279 | |
| 2280 | Sequence objects may be compared to other objects with the same |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2281 | sequence type. The comparison uses \emph{lexicographical} ordering: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2282 | first the first two items are compared, and if they differ this |
| 2283 | determines the outcome of the comparison; if they are equal, the next |
| 2284 | two items are compared, and so on, until either sequence is exhausted. |
| 2285 | If two items to be compared are themselves sequences of the same type, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2286 | the lexicographical comparison is carried out recursively. If all |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2287 | items of two sequences compare equal, the sequences are considered |
Fred Drake | 979d041 | 2001-04-03 17:41:56 +0000 | [diff] [blame] | 2288 | equal. If one sequence is an initial sub-sequence of the other, the |
Fred Drake | 20c9491 | 2001-08-01 17:17:13 +0000 | [diff] [blame] | 2289 | shorter sequence is the smaller (lesser) one. Lexicographical |
| 2290 | ordering for strings uses the \ASCII{} ordering for individual |
| 2291 | characters. Some examples of comparisons between sequences with the |
| 2292 | same types: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2293 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2294 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2295 | (1, 2, 3) < (1, 2, 4) |
| 2296 | [1, 2, 3] < [1, 2, 4] |
| 2297 | 'ABC' < 'C' < 'Pascal' < 'Python' |
| 2298 | (1, 2, 3, 4) < (1, 2, 4) |
| 2299 | (1, 2) < (1, 2, -1) |
Fred Drake | 511281a | 1999-04-16 13:17:04 +0000 | [diff] [blame] | 2300 | (1, 2, 3) == (1.0, 2.0, 3.0) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2301 | (1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2302 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2303 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2304 | Note that comparing objects of different types is legal. The outcome |
| 2305 | is deterministic but arbitrary: the types are ordered by their name. |
| 2306 | Thus, a list is always smaller than a string, a string is always |
| 2307 | smaller than a tuple, etc. Mixed numeric types are compared according |
Fred Drake | 93aa0f2 | 1999-04-05 21:39:17 +0000 | [diff] [blame] | 2308 | to their numeric value, so 0 equals 0.0, etc.\footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2309 | The rules for comparing objects of different types should |
| 2310 | not be relied upon; they may change in a future version of |
| 2311 | the language. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2312 | } |
| 2313 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2314 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2315 | \chapter{Modules \label{modules}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2316 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 2317 | If you quit from the Python interpreter and enter it again, the |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2318 | definitions you have made (functions and variables) are lost. |
| 2319 | Therefore, if you want to write a somewhat longer program, you are |
| 2320 | better off using a text editor to prepare the input for the interpreter |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2321 | and running it with that file as input instead. This is known as creating a |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2322 | \emph{script}. As your program gets longer, you may want to split it |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2323 | into several files for easier maintenance. You may also want to use a |
| 2324 | handy function that you've written in several programs without copying |
| 2325 | its definition into each program. |
| 2326 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 2327 | To support this, Python has a way to put definitions in a file and use |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2328 | them in a script or in an interactive instance of the interpreter. |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2329 | Such a file is called a \emph{module}; definitions from a module can be |
| 2330 | \emph{imported} into other modules or into the \emph{main} module (the |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2331 | collection of variables that you have access to in a script |
| 2332 | executed at the top level |
| 2333 | and in calculator mode). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2334 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2335 | A module is a file containing Python definitions and statements. The |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2336 | file name is the module name with the suffix \file{.py} appended. Within |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2337 | a module, the module's name (as a string) is available as the value of |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2338 | the global variable \code{__name__}. For instance, use your favorite text |
| 2339 | editor to create a file called \file{fibo.py} in the current directory |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2340 | with the following contents: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2341 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2342 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2343 | # Fibonacci numbers module |
| 2344 | |
| 2345 | def fib(n): # write Fibonacci series up to n |
| 2346 | a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 2347 | while b < n: |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2348 | print b, |
| 2349 | a, b = b, a+b |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2350 | |
| 2351 | def fib2(n): # return Fibonacci series up to n |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2352 | result = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2353 | a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 2354 | while b < n: |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2355 | result.append(b) |
| 2356 | a, b = b, a+b |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2357 | return result |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2358 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2359 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 2360 | Now enter the Python interpreter and import this module with the |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2361 | following command: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2362 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2363 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2364 | >>> import fibo |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2365 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2366 | |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 2367 | This does not enter the names of the functions defined in \code{fibo} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2368 | directly in the current symbol table; it only enters the module name |
Fred Drake | f1ad207 | 1999-06-30 15:32:50 +0000 | [diff] [blame] | 2369 | \code{fibo} there. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2370 | Using the module name you can access the functions: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2371 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2372 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2373 | >>> fibo.fib(1000) |
| 2374 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
| 2375 | >>> fibo.fib2(100) |
| 2376 | [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2377 | >>> fibo.__name__ |
| 2378 | 'fibo' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2379 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2380 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2381 | If you intend to use a function often you can assign it to a local name: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2382 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2383 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2384 | >>> fib = fibo.fib |
| 2385 | >>> fib(500) |
| 2386 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2387 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2388 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2389 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2390 | \section{More on Modules \label{moreModules}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2391 | |
| 2392 | A module can contain executable statements as well as function |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2393 | definitions. |
| 2394 | These statements are intended to initialize the module. |
| 2395 | They are executed only the |
| 2396 | \emph{first} time the module is imported somewhere.\footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2397 | In fact function definitions are also `statements' that are |
| 2398 | `executed'; the execution enters the function name in the |
| 2399 | module's global symbol table. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2400 | } |
| 2401 | |
| 2402 | Each module has its own private symbol table, which is used as the |
| 2403 | global symbol table by all functions defined in the module. |
| 2404 | Thus, the author of a module can use global variables in the module |
| 2405 | without worrying about accidental clashes with a user's global |
| 2406 | variables. |
| 2407 | On the other hand, if you know what you are doing you can touch a |
| 2408 | module's global variables with the same notation used to refer to its |
| 2409 | functions, |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2410 | \code{modname.itemname}. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2411 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2412 | Modules can import other modules. It is customary but not required to |
| 2413 | place all \keyword{import} statements at the beginning of a module (or |
| 2414 | script, for that matter). The imported module names are placed in the |
| 2415 | importing module's global symbol table. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2416 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2417 | There is a variant of the \keyword{import} statement that imports |
| 2418 | names from a module directly into the importing module's symbol |
| 2419 | table. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2420 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2421 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2422 | >>> from fibo import fib, fib2 |
| 2423 | >>> fib(500) |
| 2424 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2425 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2426 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2427 | This does not introduce the module name from which the imports are taken |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2428 | in the local symbol table (so in the example, \code{fibo} is not |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2429 | defined). |
| 2430 | |
| 2431 | There is even a variant to import all names that a module defines: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2432 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2433 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2434 | >>> from fibo import * |
| 2435 | >>> fib(500) |
| 2436 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2437 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2438 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2439 | This imports all names except those beginning with an underscore |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2440 | (\code{_}). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2441 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2442 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2443 | \subsection{The Module Search Path \label{searchPath}} |
Guido van Rossum | aee5e26 | 1998-08-07 17:45:09 +0000 | [diff] [blame] | 2444 | |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2445 | \indexiii{module}{search}{path} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2446 | When a module named \module{spam} is imported, the interpreter searches |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2447 | for a file named \file{spam.py} in the current directory, |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2448 | and then in the list of directories specified by |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2449 | the environment variable \envvar{PYTHONPATH}. This has the same syntax as |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2450 | the shell variable \envvar{PATH}, that is, a list of |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2451 | directory names. When \envvar{PYTHONPATH} is not set, or when the file |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2452 | is not found there, the search continues in an installation-dependent |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 2453 | default path; on \UNIX, this is usually \file{.:/usr/local/lib/python}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2454 | |
| 2455 | Actually, modules are searched in the list of directories given by the |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2456 | variable \code{sys.path} which is initialized from the directory |
| 2457 | containing the input script (or the current directory), |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2458 | \envvar{PYTHONPATH} and the installation-dependent default. This allows |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2459 | Python programs that know what they're doing to modify or replace the |
Fred Drake | ecd8157 | 2001-12-04 19:47:46 +0000 | [diff] [blame] | 2460 | module search path. Note that because the directory containing the |
| 2461 | script being run is on the search path, it is important that the |
| 2462 | script not have the same name as a standard module, or Python will |
| 2463 | attempt to load the script as a module when that module is imported. |
| 2464 | This will generally be an error. See section~\ref{standardModules}, |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 2465 | ``Standard Modules,'' for more information. |
Fred Drake | ecd8157 | 2001-12-04 19:47:46 +0000 | [diff] [blame] | 2466 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2467 | |
| 2468 | \subsection{``Compiled'' Python files} |
| 2469 | |
| 2470 | As an important speed-up of the start-up time for short programs that |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2471 | use a lot of standard modules, if a file called \file{spam.pyc} exists |
| 2472 | in the directory where \file{spam.py} is found, this is assumed to |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2473 | contain an already-``byte-compiled'' version of the module \module{spam}. |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2474 | The modification time of the version of \file{spam.py} used to create |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2475 | \file{spam.pyc} is recorded in \file{spam.pyc}, and the |
| 2476 | \file{.pyc} file is ignored if these don't match. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2477 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2478 | Normally, you don't need to do anything to create the |
| 2479 | \file{spam.pyc} file. Whenever \file{spam.py} is successfully |
| 2480 | compiled, an attempt is made to write the compiled version to |
| 2481 | \file{spam.pyc}. It is not an error if this attempt fails; if for any |
| 2482 | reason the file is not written completely, the resulting |
| 2483 | \file{spam.pyc} file will be recognized as invalid and thus ignored |
| 2484 | later. The contents of the \file{spam.pyc} file are platform |
| 2485 | independent, so a Python module directory can be shared by machines of |
| 2486 | different architectures. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2487 | |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2488 | Some tips for experts: |
| 2489 | |
| 2490 | \begin{itemize} |
| 2491 | |
| 2492 | \item |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 2493 | When the Python interpreter is invoked with the \programopt{-O} flag, |
Michael W. Hudson | dd32a91 | 2002-08-15 14:59:02 +0000 | [diff] [blame] | 2494 | optimized code is generated and stored in \file{.pyo} files. The |
| 2495 | optimizer currently doesn't help much; it only removes |
| 2496 | \keyword{assert} statements. When \programopt{-O} is used, \emph{all} |
| 2497 | bytecode is optimized; \code{.pyc} files are ignored and \code{.py} |
| 2498 | files are compiled to optimized bytecode. |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2499 | |
| 2500 | \item |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 2501 | Passing two \programopt{-O} flags to the Python interpreter |
| 2502 | (\programopt{-OO}) will cause the bytecode compiler to perform |
| 2503 | optimizations that could in some rare cases result in malfunctioning |
| 2504 | programs. Currently only \code{__doc__} strings are removed from the |
| 2505 | bytecode, resulting in more compact \file{.pyo} files. Since some |
| 2506 | programs may rely on having these available, you should only use this |
| 2507 | option if you know what you're doing. |
Guido van Rossum | 6b86a42 | 1999-01-28 15:07:47 +0000 | [diff] [blame] | 2508 | |
| 2509 | \item |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2510 | A program doesn't run any faster when it is read from a \file{.pyc} or |
| 2511 | \file{.pyo} file than when it is read from a \file{.py} file; the only |
| 2512 | thing that's faster about \file{.pyc} or \file{.pyo} files is the |
| 2513 | speed with which they are loaded. |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2514 | |
| 2515 | \item |
Guido van Rossum | 002f7aa | 1998-06-28 19:16:38 +0000 | [diff] [blame] | 2516 | When a script is run by giving its name on the command line, the |
| 2517 | bytecode for the script is never written to a \file{.pyc} or |
| 2518 | \file{.pyo} file. Thus, the startup time of a script may be reduced |
| 2519 | by moving most of its code to a module and having a small bootstrap |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2520 | script that imports that module. It is also possible to name a |
| 2521 | \file{.pyc} or \file{.pyo} file directly on the command line. |
Guido van Rossum | 002f7aa | 1998-06-28 19:16:38 +0000 | [diff] [blame] | 2522 | |
| 2523 | \item |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2524 | It is possible to have a file called \file{spam.pyc} (or |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2525 | \file{spam.pyo} when \programopt{-O} is used) without a file |
| 2526 | \file{spam.py} for the same module. This can be used to distribute a |
| 2527 | library of Python code in a form that is moderately hard to reverse |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2528 | engineer. |
| 2529 | |
| 2530 | \item |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 2531 | The module \ulink{\module{compileall}}{../lib/module-compileall.html}% |
| 2532 | {} \refstmodindex{compileall} can create \file{.pyc} files (or |
| 2533 | \file{.pyo} files when \programopt{-O} is used) for all modules in a |
| 2534 | directory. |
Guido van Rossum | 13c8ef6 | 1998-05-29 19:12:23 +0000 | [diff] [blame] | 2535 | |
| 2536 | \end{itemize} |
| 2537 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2538 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2539 | \section{Standard Modules \label{standardModules}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2540 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 2541 | Python comes with a library of standard modules, described in a separate |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 2542 | document, the \citetitle[../lib/lib.html]{Python Library Reference} |
| 2543 | (``Library Reference'' hereafter). Some modules are built into the |
| 2544 | interpreter; these provide access to operations that are not part of |
| 2545 | the core of the language but are nevertheless built in, either for |
| 2546 | efficiency or to provide access to operating system primitives such as |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2547 | system calls. The set of such modules is a configuration option which |
Martin v. Löwis | 95cf84a | 2003-10-19 07:32:24 +0000 | [diff] [blame] | 2548 | also depends on the underlying platform For example, |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 2549 | the \module{amoeba} module is only provided on systems that somehow |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2550 | support Amoeba primitives. One particular module deserves some |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 2551 | attention: \ulink{\module{sys}}{../lib/module-sys.html}% |
| 2552 | \refstmodindex{sys}, which is built into every |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 2553 | Python interpreter. The variables \code{sys.ps1} and |
| 2554 | \code{sys.ps2} define the strings used as primary and secondary |
| 2555 | prompts: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2556 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2557 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2558 | >>> import sys |
| 2559 | >>> sys.ps1 |
| 2560 | '>>> ' |
| 2561 | >>> sys.ps2 |
| 2562 | '... ' |
| 2563 | >>> sys.ps1 = 'C> ' |
| 2564 | C> print 'Yuck!' |
| 2565 | Yuck! |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 2566 | C> |
| 2567 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2568 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2569 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2570 | These two variables are only defined if the interpreter is in |
| 2571 | interactive mode. |
| 2572 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 2573 | The variable \code{sys.path} is a list of strings that determine the |
| 2574 | interpreter's search path for modules. It is initialized to a default |
| 2575 | path taken from the environment variable \envvar{PYTHONPATH}, or from |
| 2576 | a built-in default if \envvar{PYTHONPATH} is not set. You can modify |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2577 | it using standard list operations: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2578 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2579 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2580 | >>> import sys |
| 2581 | >>> sys.path.append('/ufs/guido/lib/python') |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2582 | \end{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2583 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2584 | \section{The \function{dir()} Function \label{dir}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2585 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2586 | The built-in function \function{dir()} is used to find out which names |
| 2587 | a module defines. It returns a sorted list of strings: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2588 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2589 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2590 | >>> import fibo, sys |
| 2591 | >>> dir(fibo) |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2592 | ['__name__', 'fib', 'fib2'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2593 | >>> dir(sys) |
Fred Drake | ecd8157 | 2001-12-04 19:47:46 +0000 | [diff] [blame] | 2594 | ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__', |
Guido van Rossum | 46d3dc3 | 2003-03-01 03:20:41 +0000 | [diff] [blame] | 2595 | '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv', |
| 2596 | 'builtin_module_names', 'byteorder', 'callstats', 'copyright', |
| 2597 | 'displayhook', 'exc_clear', 'exc_info', 'exc_type', 'excepthook', |
| 2598 | 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags', |
| 2599 | 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode', |
| 2600 | 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache', |
| 2601 | 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags', |
| 2602 | 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', |
| 2603 | 'version', 'version_info', 'warnoptions'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2604 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2605 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2606 | Without arguments, \function{dir()} lists the names you have defined |
| 2607 | currently: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2608 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2609 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2610 | >>> a = [1, 2, 3, 4, 5] |
| 2611 | >>> import fibo, sys |
| 2612 | >>> fib = fibo.fib |
| 2613 | >>> dir() |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2614 | ['__name__', 'a', 'fib', 'fibo', 'sys'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2615 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2616 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2617 | Note that it lists all types of names: variables, modules, functions, etc. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2618 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2619 | \function{dir()} does not list the names of built-in functions and |
| 2620 | variables. If you want a list of those, they are defined in the |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2621 | standard module \module{__builtin__}\refbimodindex{__builtin__}: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2622 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2623 | \begin{verbatim} |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 2624 | >>> import __builtin__ |
| 2625 | >>> dir(__builtin__) |
Fred Drake | ecd8157 | 2001-12-04 19:47:46 +0000 | [diff] [blame] | 2626 | ['ArithmeticError', 'AssertionError', 'AttributeError', |
| 2627 | 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', |
Neal Norwitz | d68f517 | 2002-05-29 15:54:55 +0000 | [diff] [blame] | 2628 | 'Exception', 'False', 'FloatingPointError', 'IOError', 'ImportError', |
Fred Drake | ecd8157 | 2001-12-04 19:47:46 +0000 | [diff] [blame] | 2629 | 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt', |
| 2630 | 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented', |
| 2631 | 'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning', |
Neal Norwitz | d68f517 | 2002-05-29 15:54:55 +0000 | [diff] [blame] | 2632 | 'PendingDeprecationWarning', 'ReferenceError', |
| 2633 | 'RuntimeError', 'RuntimeWarning', 'StandardError', 'StopIteration', |
| 2634 | 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', |
| 2635 | 'True', 'TypeError', 'UnboundLocalError', 'UnicodeError', 'UserWarning', |
| 2636 | 'ValueError', 'Warning', 'ZeroDivisionError', '__debug__', '__doc__', |
| 2637 | '__import__', '__name__', 'abs', 'apply', 'bool', 'buffer', |
| 2638 | 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile', 'complex', |
| 2639 | 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', |
| 2640 | 'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float', |
| 2641 | 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', |
| 2642 | 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter', |
| 2643 | 'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min', |
| 2644 | 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', |
| 2645 | 'range', 'raw_input', 'reduce', 'reload', 'repr', 'round', |
Alex Martelli | a70b191 | 2003-04-22 08:12:33 +0000 | [diff] [blame] | 2646 | 'setattr', 'slice', 'staticmethod', 'str', 'string', 'sum', 'super', |
Neal Norwitz | d68f517 | 2002-05-29 15:54:55 +0000 | [diff] [blame] | 2647 | 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2648 | \end{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2649 | |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2650 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2651 | \section{Packages \label{packages}} |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2652 | |
| 2653 | Packages are a way of structuring Python's module namespace |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2654 | by using ``dotted module names''. For example, the module name |
| 2655 | \module{A.B} designates a submodule named \samp{B} in a package named |
| 2656 | \samp{A}. Just like the use of modules saves the authors of different |
| 2657 | modules from having to worry about each other's global variable names, |
| 2658 | the use of dotted module names saves the authors of multi-module |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2659 | packages like NumPy or the Python Imaging Library from having to worry |
| 2660 | about each other's module names. |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2661 | |
| 2662 | Suppose you want to design a collection of modules (a ``package'') for |
| 2663 | the uniform handling of sound files and sound data. There are many |
| 2664 | different sound file formats (usually recognized by their extension, |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2665 | for example: \file{.wav}, \file{.aiff}, \file{.au}), so you may need |
| 2666 | to create and maintain a growing collection of modules for the |
| 2667 | conversion between the various file formats. There are also many |
| 2668 | different operations you might want to perform on sound data (such as |
| 2669 | mixing, adding echo, applying an equalizer function, creating an |
| 2670 | artificial stereo effect), so in addition you will be writing a |
| 2671 | never-ending stream of modules to perform these operations. Here's a |
| 2672 | possible structure for your package (expressed in terms of a |
| 2673 | hierarchical filesystem): |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2674 | |
| 2675 | \begin{verbatim} |
| 2676 | Sound/ Top-level package |
| 2677 | __init__.py Initialize the sound package |
| 2678 | Formats/ Subpackage for file format conversions |
| 2679 | __init__.py |
| 2680 | wavread.py |
| 2681 | wavwrite.py |
| 2682 | aiffread.py |
| 2683 | aiffwrite.py |
| 2684 | auread.py |
| 2685 | auwrite.py |
| 2686 | ... |
| 2687 | Effects/ Subpackage for sound effects |
| 2688 | __init__.py |
| 2689 | echo.py |
| 2690 | surround.py |
| 2691 | reverse.py |
| 2692 | ... |
| 2693 | Filters/ Subpackage for filters |
| 2694 | __init__.py |
| 2695 | equalizer.py |
| 2696 | vocoder.py |
| 2697 | karaoke.py |
| 2698 | ... |
| 2699 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2700 | |
Martin v. Löwis | 95cf84a | 2003-10-19 07:32:24 +0000 | [diff] [blame] | 2701 | When importing the package, Python searches through the directories |
Raymond Hettinger | 7fbd012 | 2002-10-26 03:13:57 +0000 | [diff] [blame] | 2702 | on \code{sys.path} looking for the package subdirectory. |
| 2703 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2704 | The \file{__init__.py} files are required to make Python treat the |
| 2705 | directories as containing packages; this is done to prevent |
| 2706 | directories with a common name, such as \samp{string}, from |
| 2707 | unintentionally hiding valid modules that occur later on the module |
| 2708 | search path. In the simplest case, \file{__init__.py} can just be an |
| 2709 | empty file, but it can also execute initialization code for the |
| 2710 | package or set the \code{__all__} variable, described later. |
| 2711 | |
| 2712 | Users of the package can import individual modules from the |
| 2713 | package, for example: |
| 2714 | |
| 2715 | \begin{verbatim} |
| 2716 | import Sound.Effects.echo |
| 2717 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2718 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2719 | This loads the submodule \module{Sound.Effects.echo}. It must be referenced |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2720 | with its full name. |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2721 | |
| 2722 | \begin{verbatim} |
| 2723 | Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4) |
| 2724 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2725 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2726 | An alternative way of importing the submodule is: |
| 2727 | |
| 2728 | \begin{verbatim} |
| 2729 | from Sound.Effects import echo |
| 2730 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 2731 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2732 | This also loads the submodule \module{echo}, and makes it available without |
| 2733 | its package prefix, so it can be used as follows: |
| 2734 | |
| 2735 | \begin{verbatim} |
| 2736 | echo.echofilter(input, output, delay=0.7, atten=4) |
| 2737 | \end{verbatim} |
| 2738 | |
| 2739 | Yet another variation is to import the desired function or variable directly: |
| 2740 | |
| 2741 | \begin{verbatim} |
| 2742 | from Sound.Effects.echo import echofilter |
| 2743 | \end{verbatim} |
| 2744 | |
| 2745 | Again, this loads the submodule \module{echo}, but this makes its function |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2746 | \function{echofilter()} directly available: |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2747 | |
| 2748 | \begin{verbatim} |
| 2749 | echofilter(input, output, delay=0.7, atten=4) |
| 2750 | \end{verbatim} |
| 2751 | |
| 2752 | Note that when using \code{from \var{package} import \var{item}}, the |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2753 | item can be either a submodule (or subpackage) of the package, or some |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2754 | other name defined in the package, like a function, class or |
| 2755 | variable. The \code{import} statement first tests whether the item is |
| 2756 | defined in the package; if not, it assumes it is a module and attempts |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2757 | to load it. If it fails to find it, an |
| 2758 | \exception{ImportError} exception is raised. |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2759 | |
| 2760 | Contrarily, when using syntax like \code{import |
| 2761 | \var{item.subitem.subsubitem}}, each item except for the last must be |
| 2762 | a package; the last item can be a module or a package but can't be a |
| 2763 | class or function or variable defined in the previous item. |
| 2764 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2765 | \subsection{Importing * From a Package \label{pkg-import-star}} |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2766 | %The \code{__all__} Attribute |
| 2767 | |
| 2768 | Now what happens when the user writes \code{from Sound.Effects import |
| 2769 | *}? Ideally, one would hope that this somehow goes out to the |
| 2770 | filesystem, finds which submodules are present in the package, and |
| 2771 | imports them all. Unfortunately, this operation does not work very |
| 2772 | well on Mac and Windows platforms, where the filesystem does not |
| 2773 | always have accurate information about the case of a filename! On |
| 2774 | these platforms, there is no guaranteed way to know whether a file |
| 2775 | \file{ECHO.PY} should be imported as a module \module{echo}, |
| 2776 | \module{Echo} or \module{ECHO}. (For example, Windows 95 has the |
| 2777 | annoying practice of showing all file names with a capitalized first |
| 2778 | letter.) The DOS 8+3 filename restriction adds another interesting |
| 2779 | problem for long module names. |
| 2780 | |
| 2781 | The only solution is for the package author to provide an explicit |
| 2782 | index of the package. The import statement uses the following |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2783 | convention: if a package's \file{__init__.py} code defines a list |
| 2784 | named \code{__all__}, it is taken to be the list of module names that |
| 2785 | should be imported when \code{from \var{package} import *} is |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2786 | encountered. It is up to the package author to keep this list |
| 2787 | up-to-date when a new version of the package is released. Package |
| 2788 | authors may also decide not to support it, if they don't see a use for |
| 2789 | importing * from their package. For example, the file |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2790 | \file{Sounds/Effects/__init__.py} could contain the following code: |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2791 | |
| 2792 | \begin{verbatim} |
| 2793 | __all__ = ["echo", "surround", "reverse"] |
| 2794 | \end{verbatim} |
| 2795 | |
| 2796 | This would mean that \code{from Sound.Effects import *} would |
| 2797 | import the three named submodules of the \module{Sound} package. |
| 2798 | |
| 2799 | If \code{__all__} is not defined, the statement \code{from Sound.Effects |
| 2800 | import *} does \emph{not} import all submodules from the package |
| 2801 | \module{Sound.Effects} into the current namespace; it only ensures that the |
| 2802 | package \module{Sound.Effects} has been imported (possibly running its |
| 2803 | initialization code, \file{__init__.py}) and then imports whatever names are |
| 2804 | defined in the package. This includes any names defined (and |
| 2805 | submodules explicitly loaded) by \file{__init__.py}. It also includes any |
| 2806 | submodules of the package that were explicitly loaded by previous |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 2807 | import statements. Consider this code: |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2808 | |
| 2809 | \begin{verbatim} |
| 2810 | import Sound.Effects.echo |
| 2811 | import Sound.Effects.surround |
| 2812 | from Sound.Effects import * |
| 2813 | \end{verbatim} |
| 2814 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2815 | In this example, the echo and surround modules are imported in the |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2816 | current namespace because they are defined in the |
| 2817 | \module{Sound.Effects} package when the \code{from...import} statement |
| 2818 | is executed. (This also works when \code{__all__} is defined.) |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2819 | |
Fred Drake | 55803bc | 2002-10-22 21:00:44 +0000 | [diff] [blame] | 2820 | Note that in general the practice of importing \code{*} from a module or |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2821 | package is frowned upon, since it often causes poorly readable code. |
| 2822 | However, it is okay to use it to save typing in interactive sessions, |
| 2823 | and certain modules are designed to export only names that follow |
| 2824 | certain patterns. |
| 2825 | |
| 2826 | Remember, there is nothing wrong with using \code{from Package |
| 2827 | import specific_submodule}! In fact, this is the |
| 2828 | recommended notation unless the importing module needs to use |
| 2829 | submodules with the same name from different packages. |
| 2830 | |
| 2831 | |
| 2832 | \subsection{Intra-package References} |
| 2833 | |
| 2834 | The submodules often need to refer to each other. For example, the |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 2835 | \module{surround} module might use the \module{echo} module. In fact, |
| 2836 | such references |
| 2837 | are so common that the \keyword{import} statement first looks in the |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2838 | containing package before looking in the standard module search path. |
| 2839 | Thus, the surround module can simply use \code{import echo} or |
| 2840 | \code{from echo import echofilter}. If the imported module is not |
| 2841 | found in the current package (the package of which the current module |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 2842 | is a submodule), the \keyword{import} statement looks for a top-level |
| 2843 | module with the given name. |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2844 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2845 | When packages are structured into subpackages (as with the |
| 2846 | \module{Sound} package in the example), there's no shortcut to refer |
| 2847 | to submodules of sibling packages - the full name of the subpackage |
| 2848 | must be used. For example, if the module |
| 2849 | \module{Sound.Filters.vocoder} needs to use the \module{echo} module |
| 2850 | in the \module{Sound.Effects} package, it can use \code{from |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2851 | Sound.Effects import echo}. |
| 2852 | |
Fred Drake | 55803bc | 2002-10-22 21:00:44 +0000 | [diff] [blame] | 2853 | \subsection{Packages in Multiple Directories} |
| 2854 | |
| 2855 | Packages support one more special attribute, \member{__path__}. This |
| 2856 | is initialized to be a list containing the name of the directory |
| 2857 | holding the package's \file{__init__.py} before the code in that file |
| 2858 | is executed. This variable can be modified; doing so affects future |
| 2859 | searches for modules and subpackages contained in the package. |
| 2860 | |
| 2861 | While this feature is not often needed, it can be used to extend the |
| 2862 | set of modules found in a package. |
| 2863 | |
Andrew M. Kuchling | 108943c | 1998-07-01 13:58:55 +0000 | [diff] [blame] | 2864 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2865 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2866 | \chapter{Input and Output \label{io}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2867 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2868 | There are several ways to present the output of a program; data can be |
| 2869 | printed in a human-readable form, or written to a file for future use. |
| 2870 | This chapter will discuss some of the possibilities. |
| 2871 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 2872 | |
| 2873 | \section{Fancier Output Formatting \label{formatting}} |
| 2874 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 2875 | So far we've encountered two ways of writing values: \emph{expression |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2876 | statements} and the \keyword{print} statement. (A third way is using |
| 2877 | the \method{write()} method of file objects; the standard output file |
| 2878 | can be referenced as \code{sys.stdout}. See the Library Reference for |
| 2879 | more information on this.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2880 | |
| 2881 | Often you'll want more control over the formatting of your output than |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 2882 | simply printing space-separated values. There are two ways to format |
| 2883 | your output; the first way is to do all the string handling yourself; |
| 2884 | using string slicing and concatenation operations you can create any |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 2885 | lay-out you can imagine. The standard module |
| 2886 | \module{string}\refstmodindex{string} contains some useful operations |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2887 | for padding strings to a given column width; these will be discussed |
| 2888 | shortly. The second way is to use the \code{\%} operator with a |
| 2889 | string as the left argument. The \code{\%} operator interprets the |
Fred Drake | cc97f8c | 2001-01-01 20:33:06 +0000 | [diff] [blame] | 2890 | left argument much like a \cfunction{sprintf()}-style format |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 2891 | string to be applied to the right argument, and returns the string |
| 2892 | resulting from this formatting operation. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2893 | |
| 2894 | One question remains, of course: how do you convert values to strings? |
Fred Drake | 6016dbe | 2001-12-04 19:20:43 +0000 | [diff] [blame] | 2895 | Luckily, Python has ways to convert any value to a string: pass it to |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2896 | the \function{repr()} or \function{str()} functions. Reverse quotes |
| 2897 | (\code{``}) are equivalent to \function{repr()}, but their use is |
| 2898 | discouraged. |
Fred Drake | 6016dbe | 2001-12-04 19:20:43 +0000 | [diff] [blame] | 2899 | |
| 2900 | The \function{str()} function is meant to return representations of |
| 2901 | values which are fairly human-readable, while \function{repr()} is |
| 2902 | meant to generate representations which can be read by the interpreter |
| 2903 | (or will force a \exception{SyntaxError} if there is not equivalent |
| 2904 | syntax). For objects which don't have a particular representation for |
| 2905 | human consumption, \function{str()} will return the same value as |
| 2906 | \function{repr()}. Many values, such as numbers or structures like |
| 2907 | lists and dictionaries, have the same representation using either |
| 2908 | function. Strings and floating point numbers, in particular, have two |
| 2909 | distinct representations. |
| 2910 | |
| 2911 | Some examples: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2912 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2913 | \begin{verbatim} |
Fred Drake | 6016dbe | 2001-12-04 19:20:43 +0000 | [diff] [blame] | 2914 | >>> s = 'Hello, world.' |
| 2915 | >>> str(s) |
| 2916 | 'Hello, world.' |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2917 | >>> repr(s) |
Fred Drake | 6016dbe | 2001-12-04 19:20:43 +0000 | [diff] [blame] | 2918 | "'Hello, world.'" |
| 2919 | >>> str(0.1) |
| 2920 | '0.1' |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2921 | >>> repr(0.1) |
Fred Drake | 6016dbe | 2001-12-04 19:20:43 +0000 | [diff] [blame] | 2922 | '0.10000000000000001' |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 2923 | >>> x = 10 * 3.25 |
Fred Drake | 8b0b840 | 2001-05-21 16:55:39 +0000 | [diff] [blame] | 2924 | >>> y = 200 * 200 |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2925 | >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...' |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2926 | >>> print s |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 2927 | The value of x is 32.5, and y is 40000... |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2928 | >>> # The repr() of a string adds string quotes and backslashes: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2929 | ... hello = 'hello, world\n' |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2930 | >>> hellos = repr(hello) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2931 | >>> print hellos |
Fred Drake | 0c14961 | 2001-04-12 04:26:24 +0000 | [diff] [blame] | 2932 | 'hello, world\n' |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2933 | >>> # The argument to repr() may be any Python object: |
Skip Montanaro | 45a9c93 | 2003-05-07 16:01:43 +0000 | [diff] [blame] | 2934 | ... repr((x, y, ('spam', 'eggs'))) |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 2935 | "(32.5, 40000, ('spam', 'eggs'))" |
| 2936 | >>> # reverse quotes are convenient in interactive sessions: |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 2937 | ... `x, y, ('spam', 'eggs')` |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 2938 | "(32.5, 40000, ('spam', 'eggs'))" |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2939 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2940 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2941 | Here are two ways to write a table of squares and cubes: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2942 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2943 | \begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2944 | >>> for x in range(1, 11): |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2945 | ... print repr(x).rjust(2), repr(x*x).rjust(3), |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2946 | ... # Note trailing comma on previous line |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2947 | ... print repr(x*x*x).rjust(4) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2948 | ... |
| 2949 | 1 1 1 |
| 2950 | 2 4 8 |
| 2951 | 3 9 27 |
| 2952 | 4 16 64 |
| 2953 | 5 25 125 |
| 2954 | 6 36 216 |
| 2955 | 7 49 343 |
| 2956 | 8 64 512 |
| 2957 | 9 81 729 |
| 2958 | 10 100 1000 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2959 | >>> for x in range(1,11): |
| 2960 | ... print '%2d %3d %4d' % (x, x*x, x*x*x) |
| 2961 | ... |
| 2962 | 1 1 1 |
| 2963 | 2 4 8 |
| 2964 | 3 9 27 |
| 2965 | 4 16 64 |
| 2966 | 5 25 125 |
| 2967 | 6 36 216 |
| 2968 | 7 49 343 |
| 2969 | 8 64 512 |
| 2970 | 9 81 729 |
| 2971 | 10 100 1000 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2972 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 2973 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2974 | (Note that one space between each column was added by the way |
| 2975 | \keyword{print} works: it always adds spaces between its arguments.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2976 | |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2977 | This example demonstrates the \method{rjust()} method of string objects, |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2978 | which right-justifies a string in a field of a given width by padding |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2979 | it with spaces on the left. There are similar methods |
| 2980 | \method{ljust()} and \method{center()}. These |
| 2981 | methods do not write anything, they just return a new string. If |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2982 | the input string is too long, they don't truncate it, but return it |
| 2983 | unchanged; this will mess up your column lay-out but that's usually |
| 2984 | better than the alternative, which would be lying about a value. (If |
| 2985 | you really want truncation you can always add a slice operation, as in |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2986 | \samp{x.ljust(~n)[:n]}.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2987 | |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2988 | There is another method, \method{zfill()}, which pads a |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2989 | numeric string on the left with zeros. It understands about plus and |
| 2990 | minus signs: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2991 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2992 | \begin{verbatim} |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2993 | >>> '12'.zfill(5) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2994 | '00012' |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2995 | >>> '-3.14'.zfill(7) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2996 | '-003.14' |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 2997 | >>> '3.14159265359'.zfill(5) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 2998 | '3.14159265359' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 2999 | \end{verbatim} |
Fred Drake | 31b761e | 2000-09-29 15:17:36 +0000 | [diff] [blame] | 3000 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3001 | Using the \code{\%} operator looks like this: |
| 3002 | |
| 3003 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3004 | >>> import math |
| 3005 | >>> print 'The value of PI is approximately %5.3f.' % math.pi |
| 3006 | The value of PI is approximately 3.142. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3007 | \end{verbatim} |
| 3008 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3009 | If there is more than one format in the string, you need to pass a |
| 3010 | tuple as right operand, as in this example: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3011 | |
| 3012 | \begin{verbatim} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3013 | >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3014 | >>> for name, phone in table.items(): |
| 3015 | ... print '%-10s ==> %10d' % (name, phone) |
| 3016 | ... |
| 3017 | Jack ==> 4098 |
Fred Drake | 69fbf33 | 2000-04-04 19:53:06 +0000 | [diff] [blame] | 3018 | Dcab ==> 7678 |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3019 | Sjoerd ==> 4127 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3020 | \end{verbatim} |
| 3021 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3022 | Most formats work exactly as in C and require that you pass the proper |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3023 | type; however, if you don't you get an exception, not a core dump. |
Fred Drake | db70d06 | 1998-11-17 21:59:04 +0000 | [diff] [blame] | 3024 | The \code{\%s} format is more relaxed: if the corresponding argument is |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3025 | not a string object, it is converted to string using the |
| 3026 | \function{str()} built-in function. Using \code{*} to pass the width |
| 3027 | or precision in as a separate (integer) argument is supported. The |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3028 | C formats \code{\%n} and \code{\%p} are not supported. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3029 | |
| 3030 | If you have a really long format string that you don't want to split |
| 3031 | up, it would be nice if you could reference the variables to be |
| 3032 | formatted by name instead of by position. This can be done by using |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3033 | form \code{\%(name)format}, as shown here: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3034 | |
| 3035 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3036 | >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| 3037 | >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table |
| 3038 | Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3039 | \end{verbatim} |
| 3040 | |
| 3041 | This is particularly useful in combination with the new built-in |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3042 | \function{vars()} function, which returns a dictionary containing all |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3043 | local variables. |
| 3044 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3045 | \section{Reading and Writing Files \label{files}} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3046 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3047 | % Opening files |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3048 | \function{open()}\bifuncindex{open} returns a file |
| 3049 | object\obindex{file}, and is most commonly used with two arguments: |
| 3050 | \samp{open(\var{filename}, \var{mode})}. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3051 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3052 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3053 | >>> f=open('/tmp/workfile', 'w') |
| 3054 | >>> print f |
| 3055 | <open file '/tmp/workfile', mode 'w' at 80a0960> |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3056 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3057 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3058 | The first argument is a string containing the filename. The second |
| 3059 | argument is another string containing a few characters describing the |
| 3060 | way in which the file will be used. \var{mode} can be \code{'r'} when |
| 3061 | the file will only be read, \code{'w'} for only writing (an existing |
| 3062 | file with the same name will be erased), and \code{'a'} opens the file |
| 3063 | for appending; any data written to the file is automatically added to |
| 3064 | the end. \code{'r+'} opens the file for both reading and writing. |
| 3065 | The \var{mode} argument is optional; \code{'r'} will be assumed if |
| 3066 | it's omitted. |
| 3067 | |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3068 | On Windows and the Macintosh, \code{'b'} appended to the |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3069 | mode opens the file in binary mode, so there are also modes like |
| 3070 | \code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a |
| 3071 | distinction between text and binary files; the end-of-line characters |
| 3072 | in text files are automatically altered slightly when data is read or |
| 3073 | written. This behind-the-scenes modification to file data is fine for |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3074 | \ASCII{} text files, but it'll corrupt binary data like that in JPEGs or |
| 3075 | \file{.EXE} files. Be very careful to use binary mode when reading and |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3076 | writing such files. (Note that the precise semantics of text mode on |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3077 | the Macintosh depends on the underlying C library being used.) |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3078 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3079 | \subsection{Methods of File Objects \label{fileMethods}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3080 | |
| 3081 | The rest of the examples in this section will assume that a file |
| 3082 | object called \code{f} has already been created. |
| 3083 | |
| 3084 | To read a file's contents, call \code{f.read(\var{size})}, which reads |
| 3085 | some quantity of data and returns it as a string. \var{size} is an |
| 3086 | optional numeric argument. When \var{size} is omitted or negative, |
| 3087 | the entire contents of the file will be read and returned; it's your |
| 3088 | problem if the file is twice as large as your machine's memory. |
| 3089 | Otherwise, at most \var{size} bytes are read and returned. If the end |
| 3090 | of the file has been reached, \code{f.read()} will return an empty |
| 3091 | string (\code {""}). |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3092 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3093 | >>> f.read() |
Fred Drake | 0c14961 | 2001-04-12 04:26:24 +0000 | [diff] [blame] | 3094 | 'This is the entire file.\n' |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3095 | >>> f.read() |
| 3096 | '' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3097 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3098 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3099 | \code{f.readline()} reads a single line from the file; a newline |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3100 | character (\code{\e n}) is left at the end of the string, and is only |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3101 | omitted on the last line of the file if the file doesn't end in a |
| 3102 | newline. This makes the return value unambiguous; if |
| 3103 | \code{f.readline()} returns an empty string, the end of the file has |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3104 | been reached, while a blank line is represented by \code{'\e n'}, a |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3105 | string containing only a single newline. |
| 3106 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3107 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3108 | >>> f.readline() |
Fred Drake | 0c14961 | 2001-04-12 04:26:24 +0000 | [diff] [blame] | 3109 | 'This is the first line of the file.\n' |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3110 | >>> f.readline() |
Fred Drake | 0c14961 | 2001-04-12 04:26:24 +0000 | [diff] [blame] | 3111 | 'Second line of the file\n' |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3112 | >>> f.readline() |
| 3113 | '' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3114 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3115 | |
Fred Drake | 343ad7a | 2000-09-22 04:12:27 +0000 | [diff] [blame] | 3116 | \code{f.readlines()} returns a list containing all the lines of data |
| 3117 | in the file. If given an optional parameter \var{sizehint}, it reads |
| 3118 | that many bytes from the file and enough more to complete a line, and |
| 3119 | returns the lines from that. This is often used to allow efficient |
| 3120 | reading of a large file by lines, but without having to load the |
| 3121 | entire file in memory. Only complete lines will be returned. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3122 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3123 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3124 | >>> f.readlines() |
Fred Drake | 0c14961 | 2001-04-12 04:26:24 +0000 | [diff] [blame] | 3125 | ['This is the first line of the file.\n', 'Second line of the file\n'] |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3126 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3127 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3128 | \code{f.write(\var{string})} writes the contents of \var{string} to |
| 3129 | the file, returning \code{None}. |
| 3130 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3131 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3132 | >>> f.write('This is a test\n') |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3133 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3134 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3135 | \code{f.tell()} returns an integer giving the file object's current |
| 3136 | position in the file, measured in bytes from the beginning of the |
| 3137 | file. To change the file object's position, use |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3138 | \samp{f.seek(\var{offset}, \var{from_what})}. The position is |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3139 | computed from adding \var{offset} to a reference point; the reference |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3140 | point is selected by the \var{from_what} argument. A |
| 3141 | \var{from_what} value of 0 measures from the beginning of the file, 1 |
| 3142 | uses the current file position, and 2 uses the end of the file as the |
| 3143 | reference point. \var{from_what} can be omitted and defaults to 0, |
| 3144 | using the beginning of the file as the reference point. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3145 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3146 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3147 | >>> f=open('/tmp/workfile', 'r+') |
| 3148 | >>> f.write('0123456789abcdef') |
Fred Drake | a815916 | 2001-10-16 03:25:00 +0000 | [diff] [blame] | 3149 | >>> f.seek(5) # Go to the 6th byte in the file |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3150 | >>> f.read(1) |
| 3151 | '5' |
| 3152 | >>> f.seek(-3, 2) # Go to the 3rd byte before the end |
| 3153 | >>> f.read(1) |
| 3154 | 'd' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3155 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3156 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3157 | When you're done with a file, call \code{f.close()} to close it and |
| 3158 | free up any system resources taken up by the open file. After calling |
| 3159 | \code{f.close()}, attempts to use the file object will automatically fail. |
| 3160 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3161 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3162 | >>> f.close() |
| 3163 | >>> f.read() |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3164 | Traceback (most recent call last): |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3165 | File "<stdin>", line 1, in ? |
| 3166 | ValueError: I/O operation on closed file |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3167 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3168 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3169 | File objects have some additional methods, such as |
| 3170 | \method{isatty()} and \method{truncate()} which are less frequently |
| 3171 | used; consult the Library Reference for a complete guide to file |
| 3172 | objects. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3173 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3174 | \subsection{The \module{pickle} Module \label{pickle}} |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3175 | \refstmodindex{pickle} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3176 | |
| 3177 | Strings can easily be written to and read from a file. Numbers take a |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3178 | bit more effort, since the \method{read()} method only returns |
| 3179 | strings, which will have to be passed to a function like |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 3180 | \function{int()}, which takes a string like \code{'123'} and |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3181 | returns its numeric value 123. However, when you want to save more |
| 3182 | complex data types like lists, dictionaries, or class instances, |
| 3183 | things get a lot more complicated. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3184 | |
| 3185 | Rather than have users be constantly writing and debugging code to |
| 3186 | save complicated data types, Python provides a standard module called |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 3187 | \ulink{\module{pickle}}{../lib/module-pickle.html}. This is an |
| 3188 | amazing module that can take almost |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3189 | any Python object (even some forms of Python code!), and convert it to |
| 3190 | a string representation; this process is called \dfn{pickling}. |
| 3191 | Reconstructing the object from the string representation is called |
| 3192 | \dfn{unpickling}. Between pickling and unpickling, the string |
| 3193 | representing the object may have been stored in a file or data, or |
| 3194 | sent over a network connection to some distant machine. |
| 3195 | |
| 3196 | If you have an object \code{x}, and a file object \code{f} that's been |
| 3197 | opened for writing, the simplest way to pickle the object takes only |
| 3198 | one line of code: |
| 3199 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3200 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3201 | pickle.dump(x, f) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3202 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3203 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3204 | To unpickle the object again, if \code{f} is a file object which has |
| 3205 | been opened for reading: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3206 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3207 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3208 | x = pickle.load(f) |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3209 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3210 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3211 | (There are other variants of this, used when pickling many objects or |
| 3212 | when you don't want to write the pickled data to a file; consult the |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 3213 | complete documentation for |
| 3214 | \ulink{\module{pickle}}{../lib/module-pickle.html} in the |
| 3215 | \citetitle[../lib/]{Python Library Reference}.) |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3216 | |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 3217 | \ulink{\module{pickle}}{../lib/module-pickle.html} is the standard way |
| 3218 | to make Python objects which can be stored and reused by other |
| 3219 | programs or by a future invocation of the same program; the technical |
| 3220 | term for this is a \dfn{persistent} object. Because |
| 3221 | \ulink{\module{pickle}}{../lib/module-pickle.html} is so widely used, |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3222 | many authors who write Python extensions take care to ensure that new |
| 3223 | data types such as matrices can be properly pickled and unpickled. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3224 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 3225 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3226 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3227 | \chapter{Errors and Exceptions \label{errors}} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 3228 | |
| 3229 | Until now error messages haven't been more than mentioned, but if you |
| 3230 | have tried out the examples you have probably seen some. There are |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3231 | (at least) two distinguishable kinds of errors: |
| 3232 | \emph{syntax errors} and \emph{exceptions}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 3233 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3234 | \section{Syntax Errors \label{syntaxErrors}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3235 | |
| 3236 | Syntax errors, also known as parsing errors, are perhaps the most common |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 3237 | kind of complaint you get while you are still learning Python: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3238 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3239 | \begin{verbatim} |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 3240 | >>> while True print 'Hello world' |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3241 | File "<stdin>", line 1, in ? |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 3242 | while True print 'Hello world' |
| 3243 | ^ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3244 | SyntaxError: invalid syntax |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3245 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3246 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3247 | The parser repeats the offending line and displays a little `arrow' |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3248 | pointing at the earliest point in the line where the error was |
| 3249 | detected. The error is caused by (or at least detected at) the token |
| 3250 | \emph{preceding} the arrow: in the example, the error is detected at |
| 3251 | the keyword \keyword{print}, since a colon (\character{:}) is missing |
| 3252 | before it. File name and line number are printed so you know where to |
| 3253 | look in case the input came from a script. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3254 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3255 | \section{Exceptions \label{exceptions}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3256 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 3257 | Even if a statement or expression is syntactically correct, it may |
| 3258 | cause an error when an attempt is made to execute it. |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3259 | Errors detected during execution are called \emph{exceptions} and are |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 3260 | not unconditionally fatal: you will soon learn how to handle them in |
| 3261 | Python programs. Most exceptions are not handled by programs, |
| 3262 | however, and result in error messages as shown here: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3263 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3264 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3265 | >>> 10 * (1/0) |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3266 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3267 | File "<stdin>", line 1, in ? |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 3268 | ZeroDivisionError: integer division or modulo by zero |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 3269 | >>> 4 + spam*3 |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3270 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3271 | File "<stdin>", line 1, in ? |
Andrew M. Kuchling | e7bd876 | 2002-05-02 14:31:55 +0000 | [diff] [blame] | 3272 | NameError: name 'spam' is not defined |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3273 | >>> '2' + 2 |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3274 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3275 | File "<stdin>", line 1, in ? |
Raymond Hettinger | a02469f | 2003-05-07 17:49:36 +0000 | [diff] [blame] | 3276 | TypeError: cannot concatenate 'str' and 'int' objects |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3277 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3278 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3279 | The last line of the error message indicates what happened. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3280 | Exceptions come in different types, and the type is printed as part of |
| 3281 | the message: the types in the example are |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3282 | \exception{ZeroDivisionError}, \exception{NameError} and |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3283 | \exception{TypeError}. |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3284 | The string printed as the exception type is the name of the built-in |
Fred Drake | f0ae427 | 2004-02-24 16:13:36 +0000 | [diff] [blame] | 3285 | exception that occurred. This is true for all built-in |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3286 | exceptions, but need not be true for user-defined exceptions (although |
| 3287 | it is a useful convention). |
| 3288 | Standard exception names are built-in identifiers (not reserved |
| 3289 | keywords). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3290 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3291 | The rest of the line is a detail whose interpretation depends on the |
| 3292 | exception type; its meaning is dependent on the exception type. |
| 3293 | |
| 3294 | The preceding part of the error message shows the context where the |
| 3295 | exception happened, in the form of a stack backtrace. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 3296 | In general it contains a stack backtrace listing source lines; however, |
| 3297 | it will not display lines read from standard input. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3298 | |
Fred Drake | 860106a | 2000-10-20 03:03:18 +0000 | [diff] [blame] | 3299 | The \citetitle[../lib/module-exceptions.html]{Python Library |
| 3300 | Reference} lists the built-in exceptions and their meanings. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3301 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3302 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3303 | \section{Handling Exceptions \label{handling}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3304 | |
| 3305 | It is possible to write programs that handle selected exceptions. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3306 | Look at the following example, which asks the user for input until a |
| 3307 | valid integer has been entered, but allows the user to interrupt the |
| 3308 | program (using \kbd{Control-C} or whatever the operating system |
| 3309 | supports); note that a user-generated interruption is signalled by |
| 3310 | raising the \exception{KeyboardInterrupt} exception. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3311 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3312 | \begin{verbatim} |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 3313 | >>> while True: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3314 | ... try: |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3315 | ... x = int(raw_input("Please enter a number: ")) |
| 3316 | ... break |
| 3317 | ... except ValueError: |
| 3318 | ... print "Oops! That was no valid number. Try again..." |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3319 | ... |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3320 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3321 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3322 | The \keyword{try} statement works as follows. |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3323 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3324 | \begin{itemize} |
| 3325 | \item |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3326 | First, the \emph{try clause} (the statement(s) between the |
| 3327 | \keyword{try} and \keyword{except} keywords) is executed. |
| 3328 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3329 | \item |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3330 | If no exception occurs, the \emph{except\ clause} is skipped and |
| 3331 | execution of the \keyword{try} statement is finished. |
| 3332 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3333 | \item |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3334 | If an exception occurs during execution of the try clause, the rest of |
| 3335 | the clause is skipped. Then if its type matches the exception named |
| 3336 | after the \keyword{except} keyword, the rest of the try clause is |
| 3337 | skipped, the except clause is executed, and then execution continues |
| 3338 | after the \keyword{try} statement. |
| 3339 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3340 | \item |
| 3341 | If an exception occurs which does not match the exception named in the |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3342 | except clause, it is passed on to outer \keyword{try} statements; if |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3343 | no handler is found, it is an \emph{unhandled exception} and execution |
| 3344 | stops with a message as shown above. |
| 3345 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3346 | \end{itemize} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3347 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3348 | A \keyword{try} statement may have more than one except clause, to |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3349 | specify handlers for different exceptions. At most one handler will |
| 3350 | be executed. Handlers only handle exceptions that occur in the |
| 3351 | corresponding try clause, not in other handlers of the same |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3352 | \keyword{try} statement. An except clause may name multiple exceptions |
| 3353 | as a parenthesized list, for example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3354 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3355 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3356 | ... except (RuntimeError, TypeError, NameError): |
| 3357 | ... pass |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3358 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3359 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3360 | The last except clause may omit the exception name(s), to serve as a |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3361 | wildcard. Use this with extreme caution, since it is easy to mask a |
| 3362 | real programming error in this way! It can also be used to print an |
| 3363 | error message and then re-raise the exception (allowing a caller to |
| 3364 | handle the exception as well): |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3365 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3366 | \begin{verbatim} |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 3367 | import sys |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3368 | |
| 3369 | try: |
| 3370 | f = open('myfile.txt') |
| 3371 | s = f.readline() |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 3372 | i = int(s.strip()) |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3373 | except IOError, (errno, strerror): |
| 3374 | print "I/O error(%s): %s" % (errno, strerror) |
| 3375 | except ValueError: |
| 3376 | print "Could not convert data to an integer." |
| 3377 | except: |
| 3378 | print "Unexpected error:", sys.exc_info()[0] |
| 3379 | raise |
| 3380 | \end{verbatim} |
Fred Drake | 2900ff9 | 1999-08-24 22:14:57 +0000 | [diff] [blame] | 3381 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3382 | The \keyword{try} \ldots\ \keyword{except} statement has an optional |
Fred Drake | e99d1db | 2000-04-17 14:56:31 +0000 | [diff] [blame] | 3383 | \emph{else clause}, which, when present, must follow all except |
| 3384 | clauses. It is useful for code that must be executed if the try |
| 3385 | clause does not raise an exception. For example: |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3386 | |
| 3387 | \begin{verbatim} |
Guido van Rossum | a4289a7 | 1998-07-07 20:18:06 +0000 | [diff] [blame] | 3388 | for arg in sys.argv[1:]: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3389 | try: |
| 3390 | f = open(arg, 'r') |
| 3391 | except IOError: |
| 3392 | print 'cannot open', arg |
| 3393 | else: |
| 3394 | print arg, 'has', len(f.readlines()), 'lines' |
| 3395 | f.close() |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3396 | \end{verbatim} |
| 3397 | |
Fred Drake | e99d1db | 2000-04-17 14:56:31 +0000 | [diff] [blame] | 3398 | The use of the \keyword{else} clause is better than adding additional |
| 3399 | code to the \keyword{try} clause because it avoids accidentally |
| 3400 | catching an exception that wasn't raised by the code being protected |
| 3401 | by the \keyword{try} \ldots\ \keyword{except} statement. |
| 3402 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3403 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3404 | When an exception occurs, it may have an associated value, also known as |
Thomas Wouters | f9b526d | 2000-07-16 19:05:38 +0000 | [diff] [blame] | 3405 | the exception's \emph{argument}. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3406 | The presence and type of the argument depend on the exception type. |
Raymond Hettinger | 6122d02 | 2003-07-12 01:05:37 +0000 | [diff] [blame] | 3407 | |
| 3408 | The except clause may specify a variable after the exception name (or list). |
| 3409 | The variable is bound to an exception instance with the arguments stored |
| 3410 | in \code{instance.args}. For convenience, the exception instance |
| 3411 | defines \method{__getitem__} and \method{__str__} so the arguments can |
| 3412 | be accessed or printed directly without having to reference \code{.args}. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3413 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3414 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3415 | >>> try: |
Raymond Hettinger | 6122d02 | 2003-07-12 01:05:37 +0000 | [diff] [blame] | 3416 | ... raise Exception('spam', 'eggs') |
| 3417 | ... except Exception, inst: |
| 3418 | ... print type(inst) # the exception instance |
Raymond Hettinger | b233e54 | 2003-07-15 23:16:01 +0000 | [diff] [blame] | 3419 | ... print inst.args # arguments stored in .args |
Raymond Hettinger | 6122d02 | 2003-07-12 01:05:37 +0000 | [diff] [blame] | 3420 | ... print inst # __str__ allows args to printed directly |
| 3421 | ... x, y = inst # __getitem__ allows args to be unpacked directly |
| 3422 | ... print 'x =', x |
| 3423 | ... print 'y =', y |
| 3424 | ... |
| 3425 | <type 'instance'> |
| 3426 | ('spam', 'eggs') |
| 3427 | ('spam', 'eggs') |
| 3428 | x = spam |
| 3429 | y = eggs |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3430 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3431 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3432 | If an exception has an argument, it is printed as the last part |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3433 | (`detail') of the message for unhandled exceptions. |
| 3434 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3435 | Exception handlers don't just handle exceptions if they occur |
| 3436 | immediately in the try clause, but also if they occur inside functions |
| 3437 | that are called (even indirectly) in the try clause. |
| 3438 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3439 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3440 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3441 | >>> def this_fails(): |
| 3442 | ... x = 1/0 |
| 3443 | ... |
| 3444 | >>> try: |
| 3445 | ... this_fails() |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3446 | ... except ZeroDivisionError, detail: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3447 | ... print 'Handling run-time error:', detail |
| 3448 | ... |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3449 | Handling run-time error: integer division or modulo |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3450 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3451 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3452 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3453 | \section{Raising Exceptions \label{raising}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3454 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3455 | The \keyword{raise} statement allows the programmer to force a |
| 3456 | specified exception to occur. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3457 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3458 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3459 | \begin{verbatim} |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3460 | >>> raise NameError, 'HiThere' |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3461 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3462 | File "<stdin>", line 1, in ? |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3463 | NameError: HiThere |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3464 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3465 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3466 | The first argument to \keyword{raise} names the exception to be |
| 3467 | raised. The optional second argument specifies the exception's |
| 3468 | argument. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3469 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3470 | If you need to determine whether an exception was raised but don't |
| 3471 | intend to handle it, a simpler form of the \keyword{raise} statement |
| 3472 | allows you to re-raise the exception: |
| 3473 | |
| 3474 | \begin{verbatim} |
| 3475 | >>> try: |
| 3476 | ... raise NameError, 'HiThere' |
| 3477 | ... except NameError: |
| 3478 | ... print 'An exception flew by!' |
| 3479 | ... raise |
| 3480 | ... |
| 3481 | An exception flew by! |
| 3482 | Traceback (most recent call last): |
| 3483 | File "<stdin>", line 2, in ? |
| 3484 | NameError: HiThere |
| 3485 | \end{verbatim} |
| 3486 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3487 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3488 | \section{User-defined Exceptions \label{userExceptions}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3489 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3490 | Programs may name their own exceptions by creating a new exception |
| 3491 | class. Exceptions should typically be derived from the |
| 3492 | \exception{Exception} class, either directly or indirectly. For |
| 3493 | example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3494 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3495 | \begin{verbatim} |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3496 | >>> class MyError(Exception): |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3497 | ... def __init__(self, value): |
| 3498 | ... self.value = value |
| 3499 | ... def __str__(self): |
Skip Montanaro | b4f1242 | 2003-05-07 15:29:12 +0000 | [diff] [blame] | 3500 | ... return repr(self.value) |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3501 | ... |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3502 | >>> try: |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3503 | ... raise MyError(2*2) |
| 3504 | ... except MyError, e: |
| 3505 | ... print 'My exception occurred, value:', e.value |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3506 | ... |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3507 | My exception occurred, value: 4 |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3508 | >>> raise MyError, 'oops!' |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3509 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3510 | File "<stdin>", line 1, in ? |
| 3511 | __main__.MyError: 'oops!' |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3512 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3513 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3514 | Exception classes can be defined which do anything any other class can |
| 3515 | do, but are usually kept simple, often only offering a number of |
| 3516 | attributes that allow information about the error to be extracted by |
| 3517 | handlers for the exception. When creating a module which can raise |
| 3518 | several distinct errors, a common practice is to create a base class |
| 3519 | for exceptions defined by that module, and subclass that to create |
| 3520 | specific exception classes for different error conditions: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3521 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3522 | \begin{verbatim} |
| 3523 | class Error(Exception): |
| 3524 | """Base class for exceptions in this module.""" |
| 3525 | pass |
| 3526 | |
| 3527 | class InputError(Error): |
| 3528 | """Exception raised for errors in the input. |
| 3529 | |
| 3530 | Attributes: |
| 3531 | expression -- input expression in which the error occurred |
| 3532 | message -- explanation of the error |
| 3533 | """ |
| 3534 | |
| 3535 | def __init__(self, expression, message): |
| 3536 | self.expression = expression |
| 3537 | self.message = message |
| 3538 | |
| 3539 | class TransitionError(Error): |
| 3540 | """Raised when an operation attempts a state transition that's not |
| 3541 | allowed. |
| 3542 | |
| 3543 | Attributes: |
| 3544 | previous -- state at beginning of transition |
| 3545 | next -- attempted new state |
| 3546 | message -- explanation of why the specific transition is not allowed |
| 3547 | """ |
| 3548 | |
| 3549 | def __init__(self, previous, next, message): |
| 3550 | self.previous = previous |
| 3551 | self.next = next |
| 3552 | self.message = message |
| 3553 | \end{verbatim} |
| 3554 | |
| 3555 | Most exceptions are defined with names that end in ``Error,'' similar |
| 3556 | to the naming of the standard exceptions. |
| 3557 | |
| 3558 | Many standard modules define their own exceptions to report errors |
| 3559 | that may occur in functions they define. More information on classes |
| 3560 | is presented in chapter \ref{classes}, ``Classes.'' |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3561 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3562 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3563 | \section{Defining Clean-up Actions \label{cleanup}} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3564 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3565 | The \keyword{try} statement has another optional clause which is |
| 3566 | intended to define clean-up actions that must be executed under all |
| 3567 | circumstances. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 3568 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3569 | \begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3570 | >>> try: |
| 3571 | ... raise KeyboardInterrupt |
| 3572 | ... finally: |
| 3573 | ... print 'Goodbye, world!' |
| 3574 | ... |
| 3575 | Goodbye, world! |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 3576 | Traceback (most recent call last): |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3577 | File "<stdin>", line 2, in ? |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 3578 | KeyboardInterrupt |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3579 | \end{verbatim} |
Fred Drake | 6c2176e | 1998-02-26 21:47:54 +0000 | [diff] [blame] | 3580 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3581 | A \emph{finally clause} is executed whether or not an exception has |
| 3582 | occurred in the try clause. When an exception has occurred, it is |
| 3583 | re-raised after the finally clause is executed. The finally clause is |
| 3584 | also executed ``on the way out'' when the \keyword{try} statement is |
| 3585 | left via a \keyword{break} or \keyword{return} statement. |
Guido van Rossum | da8c3fd | 1992-08-09 13:55:25 +0000 | [diff] [blame] | 3586 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3587 | The code in the finally clause is useful for releasing external |
| 3588 | resources (such as files or network connections), regardless of |
| 3589 | whether or not the use of the resource was successful. |
| 3590 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3591 | A \keyword{try} statement must either have one or more except clauses |
| 3592 | or one finally clause, but not both. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3593 | |
Fred Drake | 13af428 | 2001-09-21 21:10:05 +0000 | [diff] [blame] | 3594 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3595 | \chapter{Classes \label{classes}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3596 | |
| 3597 | Python's class mechanism adds classes to the language with a minimum |
| 3598 | of new syntax and semantics. It is a mixture of the class mechanisms |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 3599 | found in \Cpp{} and Modula-3. As is true for modules, classes in Python |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3600 | do not put an absolute barrier between definition and user, but rather |
| 3601 | rely on the politeness of the user not to ``break into the |
| 3602 | definition.'' The most important features of classes are retained |
| 3603 | with full power, however: the class inheritance mechanism allows |
| 3604 | multiple base classes, a derived class can override any methods of its |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3605 | base class or classes, a method can call the method of a base class with the |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3606 | same name. Objects can contain an arbitrary amount of private data. |
| 3607 | |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 3608 | In \Cpp{} terminology, all class members (including the data members) are |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3609 | \emph{public}, and all member functions are \emph{virtual}. There are |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3610 | no special constructors or destructors. As in Modula-3, there are no |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3611 | shorthands for referencing the object's members from its methods: the |
| 3612 | method function is declared with an explicit first argument |
| 3613 | representing the object, which is provided implicitly by the call. As |
| 3614 | in Smalltalk, classes themselves are objects, albeit in the wider |
| 3615 | sense of the word: in Python, all data types are objects. This |
Neal Norwitz | 8ed69e3 | 2003-10-25 14:15:54 +0000 | [diff] [blame] | 3616 | provides semantics for importing and renaming. Unlike |
| 3617 | \Cpp{} and Modula-3, built-in types can be used as base classes for |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 3618 | extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3619 | built-in operators with special syntax (arithmetic operators, |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3620 | subscripting etc.) can be redefined for class instances. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3621 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3622 | \section{A Word About Terminology \label{terminology}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3623 | |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3624 | Lacking universally accepted terminology to talk about classes, I will |
| 3625 | make occasional use of Smalltalk and \Cpp{} terms. (I would use Modula-3 |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3626 | terms, since its object-oriented semantics are closer to those of |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 3627 | Python than \Cpp, but I expect that few readers have heard of it.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3628 | |
| 3629 | I also have to warn you that there's a terminological pitfall for |
| 3630 | object-oriented readers: the word ``object'' in Python does not |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3631 | necessarily mean a class instance. Like \Cpp{} and Modula-3, and |
| 3632 | unlike Smalltalk, not all types in Python are classes: the basic |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3633 | built-in types like integers and lists are not, and even somewhat more |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3634 | exotic types like files aren't. However, \emph{all} Python types |
| 3635 | share a little bit of common semantics that is best described by using |
| 3636 | the word object. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3637 | |
| 3638 | Objects have individuality, and multiple names (in multiple scopes) |
| 3639 | can be bound to the same object. This is known as aliasing in other |
| 3640 | languages. This is usually not appreciated on a first glance at |
| 3641 | Python, and can be safely ignored when dealing with immutable basic |
| 3642 | types (numbers, strings, tuples). However, aliasing has an |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3643 | (intended!) effect on the semantics of Python code involving mutable |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3644 | objects such as lists, dictionaries, and most types representing |
| 3645 | entities outside the program (files, windows, etc.). This is usually |
| 3646 | used to the benefit of the program, since aliases behave like pointers |
| 3647 | in some respects. For example, passing an object is cheap since only |
| 3648 | a pointer is passed by the implementation; and if a function modifies |
| 3649 | an object passed as an argument, the caller will see the change --- this |
Raymond Hettinger | ccd615c | 2003-06-30 04:27:31 +0000 | [diff] [blame] | 3650 | eliminates the need for two different argument passing mechanisms as in |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3651 | Pascal. |
| 3652 | |
| 3653 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3654 | \section{Python Scopes and Name Spaces \label{scopes}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3655 | |
| 3656 | Before introducing classes, I first have to tell you something about |
| 3657 | Python's scope rules. Class definitions play some neat tricks with |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3658 | namespaces, and you need to know how scopes and namespaces work to |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3659 | fully understand what's going on. Incidentally, knowledge about this |
| 3660 | subject is useful for any advanced Python programmer. |
| 3661 | |
| 3662 | Let's begin with some definitions. |
| 3663 | |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3664 | A \emph{namespace} is a mapping from names to objects. Most |
| 3665 | namespaces are currently implemented as Python dictionaries, but |
| 3666 | that's normally not noticeable in any way (except for performance), |
| 3667 | and it may change in the future. Examples of namespaces are: the set |
| 3668 | of built-in names (functions such as \function{abs()}, and built-in |
| 3669 | exception names); the global names in a module; and the local names in |
| 3670 | a function invocation. In a sense the set of attributes of an object |
| 3671 | also form a namespace. The important thing to know about namespaces |
| 3672 | is that there is absolutely no relation between names in different |
| 3673 | namespaces; for instance, two different modules may both define a |
| 3674 | function ``maximize'' without confusion --- users of the modules must |
| 3675 | prefix it with the module name. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3676 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3677 | By the way, I use the word \emph{attribute} for any name following a |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3678 | dot --- for example, in the expression \code{z.real}, \code{real} is |
| 3679 | an attribute of the object \code{z}. Strictly speaking, references to |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3680 | names in modules are attribute references: in the expression |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3681 | \code{modname.funcname}, \code{modname} is a module object and |
| 3682 | \code{funcname} is an attribute of it. In this case there happens to |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3683 | be a straightforward mapping between the module's attributes and the |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3684 | global names defined in the module: they share the same namespace! |
| 3685 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3686 | Except for one thing. Module objects have a secret read-only |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3687 | attribute called \member{__dict__} which returns the dictionary |
| 3688 | used to implement the module's namespace; the name |
| 3689 | \member{__dict__} is an attribute but not a global name. |
| 3690 | Obviously, using this violates the abstraction of namespace |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3691 | implementation, and should be restricted to things like |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3692 | post-mortem debuggers. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3693 | } |
| 3694 | |
| 3695 | Attributes may be read-only or writable. In the latter case, |
| 3696 | assignment to attributes is possible. Module attributes are writable: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3697 | you can write \samp{modname.the_answer = 42}. Writable attributes may |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3698 | also be deleted with the \keyword{del} statement. For example, |
| 3699 | \samp{del modname.the_answer} will remove the attribute |
| 3700 | \member{the_answer} from the object named by \code{modname}. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3701 | |
| 3702 | Name spaces are created at different moments and have different |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3703 | lifetimes. The namespace containing the built-in names is created |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3704 | when the Python interpreter starts up, and is never deleted. The |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3705 | global namespace for a module is created when the module definition |
| 3706 | is read in; normally, module namespaces also last until the |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3707 | interpreter quits. The statements executed by the top-level |
| 3708 | invocation of the interpreter, either read from a script file or |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3709 | interactively, are considered part of a module called |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3710 | \module{__main__}, so they have their own global namespace. (The |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3711 | built-in names actually also live in a module; this is called |
| 3712 | \module{__builtin__}.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3713 | |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3714 | The local namespace for a function is created when the function is |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3715 | called, and deleted when the function returns or raises an exception |
| 3716 | that is not handled within the function. (Actually, forgetting would |
| 3717 | be a better way to describe what actually happens.) Of course, |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3718 | recursive invocations each have their own local namespace. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3719 | |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3720 | A \emph{scope} is a textual region of a Python program where a |
| 3721 | namespace is directly accessible. ``Directly accessible'' here means |
| 3722 | that an unqualified reference to a name attempts to find the name in |
| 3723 | the namespace. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3724 | |
| 3725 | Although scopes are determined statically, they are used dynamically. |
Raymond Hettinger | 861bb02 | 2002-08-07 16:09:48 +0000 | [diff] [blame] | 3726 | At any time during execution, there are at least three nested scopes whose |
| 3727 | namespaces are directly accessible: the innermost scope, which is searched |
Raymond Hettinger | ae7ef57 | 2002-08-07 20:20:52 +0000 | [diff] [blame] | 3728 | first, contains the local names; the namespaces of any enclosing |
| 3729 | functions, which are searched starting with the nearest enclosing scope; |
| 3730 | the middle scope, searched next, contains the current module's global names; |
| 3731 | and the outermost scope (searched last) is the namespace containing built-in |
| 3732 | names. |
Raymond Hettinger | 861bb02 | 2002-08-07 16:09:48 +0000 | [diff] [blame] | 3733 | |
| 3734 | If a name is declared global, then all references and assignments go |
| 3735 | directly to the middle scope containing the module's global names. |
| 3736 | Otherwise, all variables found outside of the innermost scope are read-only. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3737 | |
| 3738 | Usually, the local scope references the local names of the (textually) |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 3739 | current function. Outside of functions, the local scope references |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3740 | the same namespace as the global scope: the module's namespace. |
| 3741 | Class definitions place yet another namespace in the local scope. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3742 | |
| 3743 | It is important to realize that scopes are determined textually: the |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3744 | global scope of a function defined in a module is that module's |
| 3745 | namespace, no matter from where or by what alias the function is |
| 3746 | called. On the other hand, the actual search for names is done |
| 3747 | dynamically, at run time --- however, the language definition is |
| 3748 | evolving towards static name resolution, at ``compile'' time, so don't |
| 3749 | rely on dynamic name resolution! (In fact, local variables are |
| 3750 | already determined statically.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3751 | |
| 3752 | A special quirk of Python is that assignments always go into the |
| 3753 | innermost scope. Assignments do not copy data --- they just |
| 3754 | bind names to objects. The same is true for deletions: the statement |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3755 | \samp{del x} removes the binding of \code{x} from the namespace |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 3756 | referenced by the local scope. In fact, all operations that introduce |
| 3757 | new names use the local scope: in particular, import statements and |
| 3758 | function definitions bind the module or function name in the local |
| 3759 | scope. (The \keyword{global} statement can be used to indicate that |
| 3760 | particular variables live in the global scope.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3761 | |
| 3762 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3763 | \section{A First Look at Classes \label{firstClasses}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3764 | |
| 3765 | Classes introduce a little bit of new syntax, three new object types, |
| 3766 | and some new semantics. |
| 3767 | |
| 3768 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3769 | \subsection{Class Definition Syntax \label{classDefinition}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3770 | |
| 3771 | The simplest form of class definition looks like this: |
| 3772 | |
| 3773 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3774 | class ClassName: |
| 3775 | <statement-1> |
| 3776 | . |
| 3777 | . |
| 3778 | . |
| 3779 | <statement-N> |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3780 | \end{verbatim} |
| 3781 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3782 | Class definitions, like function definitions |
| 3783 | (\keyword{def} statements) must be executed before they have any |
| 3784 | effect. (You could conceivably place a class definition in a branch |
| 3785 | of an \keyword{if} statement, or inside a function.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3786 | |
| 3787 | In practice, the statements inside a class definition will usually be |
| 3788 | function definitions, but other statements are allowed, and sometimes |
| 3789 | useful --- we'll come back to this later. The function definitions |
| 3790 | inside a class normally have a peculiar form of argument list, |
| 3791 | dictated by the calling conventions for methods --- again, this is |
| 3792 | explained later. |
| 3793 | |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3794 | When a class definition is entered, a new namespace is created, and |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3795 | used as the local scope --- thus, all assignments to local variables |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3796 | go into this new namespace. In particular, function definitions bind |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3797 | the name of the new function here. |
| 3798 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3799 | When a class definition is left normally (via the end), a \emph{class |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3800 | object} is created. This is basically a wrapper around the contents |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3801 | of the namespace created by the class definition; we'll learn more |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3802 | about class objects in the next section. The original local scope |
| 3803 | (the one in effect just before the class definitions was entered) is |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 3804 | reinstated, and the class object is bound here to the class name given |
| 3805 | in the class definition header (\class{ClassName} in the example). |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3806 | |
| 3807 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3808 | \subsection{Class Objects \label{classObjects}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3809 | |
| 3810 | Class objects support two kinds of operations: attribute references |
| 3811 | and instantiation. |
| 3812 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3813 | \emph{Attribute references} use the standard syntax used for all |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3814 | attribute references in Python: \code{obj.name}. Valid attribute |
Fred Drake | 1349437 | 2000-09-12 16:23:48 +0000 | [diff] [blame] | 3815 | names are all the names that were in the class's namespace when the |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3816 | class object was created. So, if the class definition looked like |
| 3817 | this: |
| 3818 | |
| 3819 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3820 | class MyClass: |
| 3821 | "A simple example class" |
| 3822 | i = 12345 |
Fred Drake | 88e6625 | 2001-06-29 17:50:57 +0000 | [diff] [blame] | 3823 | def f(self): |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3824 | return 'hello world' |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3825 | \end{verbatim} |
| 3826 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3827 | then \code{MyClass.i} and \code{MyClass.f} are valid attribute |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3828 | references, returning an integer and a method object, respectively. |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 3829 | Class attributes can also be assigned to, so you can change the value |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3830 | of \code{MyClass.i} by assignment. \member{__doc__} is also a valid |
| 3831 | attribute, returning the docstring belonging to the class: \code{"A |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 3832 | simple example class"}. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3833 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3834 | Class \emph{instantiation} uses function notation. Just pretend that |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3835 | the class object is a parameterless function that returns a new |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3836 | instance of the class. For example (assuming the above class): |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3837 | |
| 3838 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3839 | x = MyClass() |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3840 | \end{verbatim} |
| 3841 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3842 | creates a new \emph{instance} of the class and assigns this object to |
| 3843 | the local variable \code{x}. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3844 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3845 | The instantiation operation (``calling'' a class object) creates an |
| 3846 | empty object. Many classes like to create objects in a known initial |
| 3847 | state. Therefore a class may define a special method named |
| 3848 | \method{__init__()}, like this: |
| 3849 | |
| 3850 | \begin{verbatim} |
| 3851 | def __init__(self): |
| 3852 | self.data = [] |
| 3853 | \end{verbatim} |
| 3854 | |
| 3855 | When a class defines an \method{__init__()} method, class |
| 3856 | instantiation automatically invokes \method{__init__()} for the |
| 3857 | newly-created class instance. So in this example, a new, initialized |
| 3858 | instance can be obtained by: |
| 3859 | |
| 3860 | \begin{verbatim} |
| 3861 | x = MyClass() |
| 3862 | \end{verbatim} |
| 3863 | |
| 3864 | Of course, the \method{__init__()} method may have arguments for |
| 3865 | greater flexibility. In that case, arguments given to the class |
| 3866 | instantiation operator are passed on to \method{__init__()}. For |
| 3867 | example, |
| 3868 | |
| 3869 | \begin{verbatim} |
| 3870 | >>> class Complex: |
| 3871 | ... def __init__(self, realpart, imagpart): |
| 3872 | ... self.r = realpart |
| 3873 | ... self.i = imagpart |
| 3874 | ... |
Tim Peters | bd695a7 | 2001-05-22 06:54:14 +0000 | [diff] [blame] | 3875 | >>> x = Complex(3.0, -4.5) |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3876 | >>> x.r, x.i |
| 3877 | (3.0, -4.5) |
| 3878 | \end{verbatim} |
| 3879 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3880 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3881 | \subsection{Instance Objects \label{instanceObjects}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3882 | |
| 3883 | Now what can we do with instance objects? The only operations |
| 3884 | understood by instance objects are attribute references. There are |
| 3885 | two kinds of valid attribute names. |
| 3886 | |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3887 | The first I'll call \emph{data attributes}. These correspond to |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3888 | ``instance variables'' in Smalltalk, and to ``data members'' in |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 3889 | \Cpp. Data attributes need not be declared; like local variables, |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3890 | they spring into existence when they are first assigned to. For |
| 3891 | example, if \code{x} is the instance of \class{MyClass} created above, |
| 3892 | the following piece of code will print the value \code{16}, without |
| 3893 | leaving a trace: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3894 | |
| 3895 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3896 | x.counter = 1 |
| 3897 | while x.counter < 10: |
| 3898 | x.counter = x.counter * 2 |
| 3899 | print x.counter |
| 3900 | del x.counter |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3901 | \end{verbatim} |
| 3902 | |
| 3903 | The second kind of attribute references understood by instance objects |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3904 | are \emph{methods}. A method is a function that ``belongs to'' an |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3905 | object. (In Python, the term method is not unique to class instances: |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3906 | other object types can have methods as well. For example, list objects have |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3907 | methods called append, insert, remove, sort, and so on. However, |
| 3908 | below, we'll use the term method exclusively to mean methods of class |
| 3909 | instance objects, unless explicitly stated otherwise.) |
| 3910 | |
| 3911 | Valid method names of an instance object depend on its class. By |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3912 | definition, all attributes of a class that are (user-defined) function |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3913 | objects define corresponding methods of its instances. So in our |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3914 | example, \code{x.f} is a valid method reference, since |
| 3915 | \code{MyClass.f} is a function, but \code{x.i} is not, since |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3916 | \code{MyClass.i} is not. But \code{x.f} is not the same thing as |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 3917 | \code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not |
| 3918 | a function object. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3919 | |
| 3920 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3921 | \subsection{Method Objects \label{methodObjects}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3922 | |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3923 | Usually, a method is called immediately: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3924 | |
| 3925 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3926 | x.f() |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3927 | \end{verbatim} |
| 3928 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3929 | In our example, this will return the string \code{'hello world'}. |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3930 | However, it is not necessary to call a method right away: |
| 3931 | \code{x.f} is a method object, and can be stored away and called at a |
| 3932 | later time. For example: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3933 | |
| 3934 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3935 | xf = x.f |
Raymond Hettinger | a6e16a8 | 2002-08-21 04:54:00 +0000 | [diff] [blame] | 3936 | while True: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3937 | print xf() |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3938 | \end{verbatim} |
| 3939 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3940 | will continue to print \samp{hello world} until the end of time. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3941 | |
| 3942 | What exactly happens when a method is called? You may have noticed |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3943 | that \code{x.f()} was called without an argument above, even though |
| 3944 | the function definition for \method{f} specified an argument. What |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3945 | happened to the argument? Surely Python raises an exception when a |
| 3946 | function that requires an argument is called without any --- even if |
| 3947 | the argument isn't actually used... |
| 3948 | |
| 3949 | Actually, you may have guessed the answer: the special thing about |
| 3950 | methods is that the object is passed as the first argument of the |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 3951 | function. In our example, the call \code{x.f()} is exactly equivalent |
| 3952 | to \code{MyClass.f(x)}. In general, calling a method with a list of |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 3953 | \var{n} arguments is equivalent to calling the corresponding function |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3954 | with an argument list that is created by inserting the method's object |
| 3955 | before the first argument. |
| 3956 | |
| 3957 | If you still don't understand how methods work, a look at the |
| 3958 | implementation can perhaps clarify matters. When an instance |
| 3959 | attribute is referenced that isn't a data attribute, its class is |
| 3960 | searched. If the name denotes a valid class attribute that is a |
| 3961 | function object, a method object is created by packing (pointers to) |
| 3962 | the instance object and the function object just found together in an |
| 3963 | abstract object: this is the method object. When the method object is |
| 3964 | called with an argument list, it is unpacked again, a new argument |
| 3965 | list is constructed from the instance object and the original argument |
| 3966 | list, and the function object is called with this new argument list. |
| 3967 | |
| 3968 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 3969 | \section{Random Remarks \label{remarks}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3970 | |
Raymond Hettinger | d446230 | 2003-11-26 17:52:45 +0000 | [diff] [blame] | 3971 | % [These should perhaps be placed more carefully...] |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3972 | |
| 3973 | |
| 3974 | Data attributes override method attributes with the same name; to |
| 3975 | avoid accidental name conflicts, which may cause hard-to-find bugs in |
| 3976 | large programs, it is wise to use some kind of convention that |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 3977 | minimizes the chance of conflicts. Possible conventions include |
| 3978 | capitalizing method names, prefixing data attribute names with a small |
| 3979 | unique string (perhaps just an underscore), or using verbs for methods |
| 3980 | and nouns for data attributes. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3981 | |
| 3982 | |
| 3983 | Data attributes may be referenced by methods as well as by ordinary |
| 3984 | users (``clients'') of an object. In other words, classes are not |
| 3985 | usable to implement pure abstract data types. In fact, nothing in |
| 3986 | Python makes it possible to enforce data hiding --- it is all based |
| 3987 | upon convention. (On the other hand, the Python implementation, |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3988 | written in C, can completely hide implementation details and control |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3989 | access to an object if necessary; this can be used by extensions to |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 3990 | Python written in C.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3991 | |
| 3992 | |
| 3993 | Clients should use data attributes with care --- clients may mess up |
| 3994 | invariants maintained by the methods by stamping on their data |
| 3995 | attributes. Note that clients may add data attributes of their own to |
| 3996 | an instance object without affecting the validity of the methods, as |
| 3997 | long as name conflicts are avoided --- again, a naming convention can |
| 3998 | save a lot of headaches here. |
| 3999 | |
| 4000 | |
| 4001 | There is no shorthand for referencing data attributes (or other |
| 4002 | methods!) from within methods. I find that this actually increases |
| 4003 | the readability of methods: there is no chance of confusing local |
| 4004 | variables and instance variables when glancing through a method. |
| 4005 | |
| 4006 | |
| 4007 | Conventionally, the first argument of methods is often called |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4008 | \code{self}. This is nothing more than a convention: the name |
| 4009 | \code{self} has absolutely no special meaning to Python. (Note, |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4010 | however, that by not following the convention your code may be less |
| 4011 | readable by other Python programmers, and it is also conceivable that |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 4012 | a \emph{class browser} program be written which relies upon such a |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4013 | convention.) |
| 4014 | |
| 4015 | |
| 4016 | Any function object that is a class attribute defines a method for |
| 4017 | instances of that class. It is not necessary that the function |
| 4018 | definition is textually enclosed in the class definition: assigning a |
| 4019 | function object to a local variable in the class is also ok. For |
| 4020 | example: |
| 4021 | |
| 4022 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4023 | # Function defined outside the class |
| 4024 | def f1(self, x, y): |
| 4025 | return min(x, x+y) |
| 4026 | |
| 4027 | class C: |
| 4028 | f = f1 |
| 4029 | def g(self): |
| 4030 | return 'hello world' |
| 4031 | h = g |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4032 | \end{verbatim} |
| 4033 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4034 | Now \code{f}, \code{g} and \code{h} are all attributes of class |
| 4035 | \class{C} that refer to function objects, and consequently they are all |
| 4036 | methods of instances of \class{C} --- \code{h} being exactly equivalent |
| 4037 | to \code{g}. Note that this practice usually only serves to confuse |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4038 | the reader of a program. |
| 4039 | |
| 4040 | |
| 4041 | Methods may call other methods by using method attributes of the |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 4042 | \code{self} argument: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4043 | |
| 4044 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4045 | class Bag: |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 4046 | def __init__(self): |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4047 | self.data = [] |
| 4048 | def add(self, x): |
| 4049 | self.data.append(x) |
| 4050 | def addtwice(self, x): |
| 4051 | self.add(x) |
| 4052 | self.add(x) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4053 | \end{verbatim} |
| 4054 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4055 | Methods may reference global names in the same way as ordinary |
| 4056 | functions. The global scope associated with a method is the module |
| 4057 | containing the class definition. (The class itself is never used as a |
| 4058 | global scope!) While one rarely encounters a good reason for using |
| 4059 | global data in a method, there are many legitimate uses of the global |
| 4060 | scope: for one thing, functions and modules imported into the global |
| 4061 | scope can be used by methods, as well as functions and classes defined |
| 4062 | in it. Usually, the class containing the method is itself defined in |
| 4063 | this global scope, and in the next section we'll find some good |
| 4064 | reasons why a method would want to reference its own class! |
| 4065 | |
| 4066 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4067 | \section{Inheritance \label{inheritance}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4068 | |
| 4069 | Of course, a language feature would not be worthy of the name ``class'' |
| 4070 | without supporting inheritance. The syntax for a derived class |
| 4071 | definition looks as follows: |
| 4072 | |
| 4073 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4074 | class DerivedClassName(BaseClassName): |
| 4075 | <statement-1> |
| 4076 | . |
| 4077 | . |
| 4078 | . |
| 4079 | <statement-N> |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4080 | \end{verbatim} |
| 4081 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4082 | The name \class{BaseClassName} must be defined in a scope containing |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4083 | the derived class definition. Instead of a base class name, an |
| 4084 | expression is also allowed. This is useful when the base class is |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 4085 | defined in another module, |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4086 | |
| 4087 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4088 | class DerivedClassName(modname.BaseClassName): |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4089 | \end{verbatim} |
| 4090 | |
| 4091 | Execution of a derived class definition proceeds the same as for a |
| 4092 | base class. When the class object is constructed, the base class is |
| 4093 | remembered. This is used for resolving attribute references: if a |
| 4094 | requested attribute is not found in the class, it is searched in the |
| 4095 | base class. This rule is applied recursively if the base class itself |
| 4096 | is derived from some other class. |
| 4097 | |
| 4098 | There's nothing special about instantiation of derived classes: |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4099 | \code{DerivedClassName()} creates a new instance of the class. Method |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4100 | references are resolved as follows: the corresponding class attribute |
| 4101 | is searched, descending down the chain of base classes if necessary, |
| 4102 | and the method reference is valid if this yields a function object. |
| 4103 | |
| 4104 | Derived classes may override methods of their base classes. Because |
| 4105 | methods have no special privileges when calling other methods of the |
| 4106 | same object, a method of a base class that calls another method |
| 4107 | defined in the same base class, may in fact end up calling a method of |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 4108 | a derived class that overrides it. (For \Cpp{} programmers: all methods |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 4109 | in Python are effectively \keyword{virtual}.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4110 | |
| 4111 | An overriding method in a derived class may in fact want to extend |
| 4112 | rather than simply replace the base class method of the same name. |
| 4113 | There is a simple way to call the base class method directly: just |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4114 | call \samp{BaseClassName.methodname(self, arguments)}. This is |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4115 | occasionally useful to clients as well. (Note that this only works if |
| 4116 | the base class is defined or imported directly in the global scope.) |
| 4117 | |
| 4118 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4119 | \subsection{Multiple Inheritance \label{multiple}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4120 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 4121 | Python supports a limited form of multiple inheritance as well. A |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4122 | class definition with multiple base classes looks as follows: |
| 4123 | |
| 4124 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4125 | class DerivedClassName(Base1, Base2, Base3): |
| 4126 | <statement-1> |
| 4127 | . |
| 4128 | . |
| 4129 | . |
| 4130 | <statement-N> |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4131 | \end{verbatim} |
| 4132 | |
| 4133 | The only rule necessary to explain the semantics is the resolution |
| 4134 | rule used for class attribute references. This is depth-first, |
| 4135 | left-to-right. Thus, if an attribute is not found in |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4136 | \class{DerivedClassName}, it is searched in \class{Base1}, then |
| 4137 | (recursively) in the base classes of \class{Base1}, and only if it is |
| 4138 | not found there, it is searched in \class{Base2}, and so on. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4139 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4140 | (To some people breadth first --- searching \class{Base2} and |
| 4141 | \class{Base3} before the base classes of \class{Base1} --- looks more |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4142 | natural. However, this would require you to know whether a particular |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4143 | attribute of \class{Base1} is actually defined in \class{Base1} or in |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4144 | one of its base classes before you can figure out the consequences of |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4145 | a name conflict with an attribute of \class{Base2}. The depth-first |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4146 | rule makes no differences between direct and inherited attributes of |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4147 | \class{Base1}.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4148 | |
| 4149 | It is clear that indiscriminate use of multiple inheritance is a |
| 4150 | maintenance nightmare, given the reliance in Python on conventions to |
| 4151 | avoid accidental name conflicts. A well-known problem with multiple |
| 4152 | inheritance is a class derived from two classes that happen to have a |
| 4153 | common base class. While it is easy enough to figure out what happens |
| 4154 | in this case (the instance will have a single copy of ``instance |
| 4155 | variables'' or data attributes used by the common base class), it is |
| 4156 | not clear that these semantics are in any way useful. |
| 4157 | |
| 4158 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4159 | \section{Private Variables \label{private}} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4160 | |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 4161 | There is limited support for class-private |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4162 | identifiers. Any identifier of the form \code{__spam} (at least two |
Andrew M. Kuchling | cbddabf | 2004-03-21 22:12:45 +0000 | [diff] [blame^] | 4163 | leading underscores, at most one trailing underscore) is textually |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4164 | replaced with \code{_classname__spam}, where \code{classname} is the |
| 4165 | current class name with leading underscore(s) stripped. This mangling |
| 4166 | is done without regard of the syntactic position of the identifier, so |
| 4167 | it can be used to define class-private instance and class variables, |
| 4168 | methods, as well as globals, and even to store instance variables |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 4169 | private to this class on instances of \emph{other} classes. Truncation |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4170 | may occur when the mangled name would be longer than 255 characters. |
| 4171 | Outside classes, or when the class name consists of only underscores, |
| 4172 | no mangling occurs. |
| 4173 | |
| 4174 | Name mangling is intended to give classes an easy way to define |
| 4175 | ``private'' instance variables and methods, without having to worry |
| 4176 | about instance variables defined by derived classes, or mucking with |
| 4177 | instance variables by code outside the class. Note that the mangling |
| 4178 | rules are designed mostly to avoid accidents; it still is possible for |
| 4179 | a determined soul to access or modify a variable that is considered |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 4180 | private. This can even be useful in special circumstances, such as in |
| 4181 | the debugger, and that's one reason why this loophole is not closed. |
| 4182 | (Buglet: derivation of a class with the same name as the base class |
| 4183 | makes use of private variables of the base class possible.) |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4184 | |
| 4185 | Notice that code passed to \code{exec}, \code{eval()} or |
| 4186 | \code{evalfile()} does not consider the classname of the invoking |
| 4187 | class to be the current class; this is similar to the effect of the |
| 4188 | \code{global} statement, the effect of which is likewise restricted to |
| 4189 | code that is byte-compiled together. The same restriction applies to |
| 4190 | \code{getattr()}, \code{setattr()} and \code{delattr()}, as well as |
| 4191 | when referencing \code{__dict__} directly. |
| 4192 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4193 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4194 | \section{Odds and Ends \label{odds}} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4195 | |
| 4196 | Sometimes it is useful to have a data type similar to the Pascal |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 4197 | ``record'' or C ``struct'', bundling together a couple of named data |
Fred Drake | ed51494 | 2001-07-06 17:28:39 +0000 | [diff] [blame] | 4198 | items. An empty class definition will do nicely: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4199 | |
| 4200 | \begin{verbatim} |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4201 | class Employee: |
| 4202 | pass |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4203 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4204 | john = Employee() # Create an empty employee record |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4205 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4206 | # Fill the fields of the record |
| 4207 | john.name = 'John Doe' |
| 4208 | john.dept = 'computer lab' |
| 4209 | john.salary = 1000 |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4210 | \end{verbatim} |
| 4211 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4212 | A piece of Python code that expects a particular abstract data type |
| 4213 | can often be passed a class that emulates the methods of that data |
| 4214 | type instead. For instance, if you have a function that formats some |
| 4215 | data from a file object, you can define a class with methods |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4216 | \method{read()} and \method{readline()} that gets the data from a string |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 4217 | buffer instead, and pass it as an argument.% (Unfortunately, this |
| 4218 | %technique has its limitations: a class can't define operations that |
| 4219 | %are accessed by special syntax such as sequence subscripting or |
| 4220 | %arithmetic operators, and assigning such a ``pseudo-file'' to |
| 4221 | %\code{sys.stdin} will not cause the interpreter to read further input |
| 4222 | %from it.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4223 | |
| 4224 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4225 | Instance method objects have attributes, too: \code{m.im_self} is the |
| 4226 | object of which the method is an instance, and \code{m.im_func} is the |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 4227 | function object corresponding to the method. |
| 4228 | |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4229 | |
| 4230 | \section{Exceptions Are Classes Too\label{exceptionClasses}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4231 | |
Raymond Hettinger | 8ee0060 | 2003-07-01 06:19:34 +0000 | [diff] [blame] | 4232 | User-defined exceptions are identified by classes as well. Using this |
| 4233 | mechanism it is possible to create extensible hierarchies of exceptions. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4234 | |
| 4235 | There are two new valid (semantic) forms for the raise statement: |
| 4236 | |
| 4237 | \begin{verbatim} |
| 4238 | raise Class, instance |
| 4239 | |
| 4240 | raise instance |
| 4241 | \end{verbatim} |
| 4242 | |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 4243 | In the first form, \code{instance} must be an instance of |
| 4244 | \class{Class} or of a class derived from it. The second form is a |
| 4245 | shorthand for: |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4246 | |
| 4247 | \begin{verbatim} |
| 4248 | raise instance.__class__, instance |
| 4249 | \end{verbatim} |
| 4250 | |
Raymond Hettinger | 8ee0060 | 2003-07-01 06:19:34 +0000 | [diff] [blame] | 4251 | A class in an except clause is compatible with an exception if it is the same |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4252 | class or a base class thereof (but not the other way around --- an |
| 4253 | except clause listing a derived class is not compatible with a base |
| 4254 | class). For example, the following code will print B, C, D in that |
| 4255 | order: |
| 4256 | |
| 4257 | \begin{verbatim} |
| 4258 | class B: |
| 4259 | pass |
| 4260 | class C(B): |
| 4261 | pass |
| 4262 | class D(C): |
| 4263 | pass |
| 4264 | |
| 4265 | for c in [B, C, D]: |
| 4266 | try: |
| 4267 | raise c() |
| 4268 | except D: |
| 4269 | print "D" |
| 4270 | except C: |
| 4271 | print "C" |
| 4272 | except B: |
| 4273 | print "B" |
| 4274 | \end{verbatim} |
| 4275 | |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 4276 | Note that if the except clauses were reversed (with |
| 4277 | \samp{except B} first), it would have printed B, B, B --- the first |
| 4278 | matching except clause is triggered. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4279 | |
| 4280 | When an error message is printed for an unhandled exception which is a |
| 4281 | class, the class name is printed, then a colon and a space, and |
| 4282 | finally the instance converted to a string using the built-in function |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4283 | \function{str()}. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4284 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4285 | |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4286 | \section{Iterators\label{iterators}} |
| 4287 | |
Raymond Hettinger | b1e5b50 | 2004-02-12 09:50:42 +0000 | [diff] [blame] | 4288 | By now, you've probably noticed that most container objects can be looped |
Fred Drake | e6ed33a | 2004-02-12 14:35:18 +0000 | [diff] [blame] | 4289 | over using a \keyword{for} statement: |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4290 | |
| 4291 | \begin{verbatim} |
| 4292 | for element in [1, 2, 3]: |
| 4293 | print element |
| 4294 | for element in (1, 2, 3): |
| 4295 | print element |
| 4296 | for key in {'one':1, 'two':2}: |
| 4297 | print key |
| 4298 | for char in "123": |
| 4299 | print char |
| 4300 | for line in open("myfile.txt"): |
| 4301 | print line |
| 4302 | \end{verbatim} |
| 4303 | |
| 4304 | This style of access is clear, concise, and convenient. The use of iterators |
Fred Drake | e6ed33a | 2004-02-12 14:35:18 +0000 | [diff] [blame] | 4305 | pervades and unifies Python. Behind the scenes, the \keyword{for} |
| 4306 | statement calls \function{iter()} on the container object. The |
| 4307 | function returns an iterator object that defines the method |
| 4308 | \method{next()} which accesses elements in the container one at a |
| 4309 | time. When there are no more elements, \method{next()} raises a |
| 4310 | \exception{StopIteration} exception which tells the \keyword{for} loop |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4311 | to terminate. This example shows how it all works: |
| 4312 | |
| 4313 | \begin{verbatim} |
| 4314 | >>> s = 'abc' |
| 4315 | >>> it = iter(s) |
| 4316 | >>> it |
| 4317 | <iterator object at 0x00A1DB50> |
| 4318 | >>> it.next() |
| 4319 | 'a' |
| 4320 | >>> it.next() |
| 4321 | 'b' |
| 4322 | >>> it.next() |
| 4323 | 'c' |
| 4324 | >>> it.next() |
| 4325 | |
| 4326 | Traceback (most recent call last): |
| 4327 | File "<pyshell#6>", line 1, in -toplevel- |
| 4328 | it.next() |
| 4329 | StopIteration |
| 4330 | \end{verbatim} |
| 4331 | |
| 4332 | Having seen the mechanics behind the iterator protocol, it is easy to add |
| 4333 | iterator behavior to your classes. Define a \method{__iter__()} method |
| 4334 | which returns an object with a \method{next()} method. If the class defines |
| 4335 | \method{next()}, then \method{__iter__()} can just return \code{self}: |
| 4336 | |
| 4337 | \begin{verbatim} |
| 4338 | >>> class Reverse: |
| 4339 | "Iterator for looping over a sequence backwards" |
| 4340 | def __init__(self, data): |
| 4341 | self.data = data |
| 4342 | self.index = len(data) |
| 4343 | def __iter__(self): |
| 4344 | return self |
| 4345 | def next(self): |
| 4346 | if self.index == 0: |
| 4347 | raise StopIteration |
| 4348 | self.index = self.index - 1 |
| 4349 | return self.data[self.index] |
| 4350 | |
| 4351 | >>> for char in Reverse('spam'): |
| 4352 | print char |
| 4353 | |
| 4354 | m |
| 4355 | a |
| 4356 | p |
| 4357 | s |
| 4358 | \end{verbatim} |
| 4359 | |
| 4360 | |
| 4361 | \section{Generators\label{generators}} |
| 4362 | |
| 4363 | Generators are a simple and powerful tool for creating iterators. They are |
| 4364 | written like regular functions but use the \keyword{yield} statement whenever |
| 4365 | they want to return data. Each time the \method{next()} is called, the |
| 4366 | generator resumes where it left-off (it remembers all the data values and |
| 4367 | which statement was last executed). An example shows that generators can |
| 4368 | be trivially easy to create: |
| 4369 | |
| 4370 | \begin{verbatim} |
| 4371 | >>> def reverse(data): |
Raymond Hettinger | 16434b5 | 2003-09-24 03:58:56 +0000 | [diff] [blame] | 4372 | for index in range(len(data)-1, -1, -1): |
| 4373 | yield data[index] |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4374 | |
| 4375 | >>> for char in reverse('golf'): |
Raymond Hettinger | 16434b5 | 2003-09-24 03:58:56 +0000 | [diff] [blame] | 4376 | print char |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4377 | |
| 4378 | f |
| 4379 | l |
| 4380 | o |
| 4381 | g |
| 4382 | \end{verbatim} |
| 4383 | |
| 4384 | Anything that can be done with generators can also be done with class based |
| 4385 | iterators as described in the previous section. What makes generators so |
| 4386 | compact is that the \method{__iter__()} and \method{next()} methods are |
| 4387 | created automatically. |
| 4388 | |
Raymond Hettinger | b233e54 | 2003-07-15 23:16:01 +0000 | [diff] [blame] | 4389 | Another key feature is that the local variables and execution state |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4390 | are automatically saved between calls. This made the function easier to write |
| 4391 | and much more clear than an approach using class variables like |
| 4392 | \code{self.index} and \code{self.data}. |
| 4393 | |
| 4394 | In addition to automatic method creation and saving program state, when |
| 4395 | generators terminate, they automatically raise \exception{StopIteration}. |
| 4396 | In combination, these features make it easy to create iterators with no |
| 4397 | more effort than writing a regular function. |
| 4398 | |
| 4399 | |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4400 | |
| 4401 | \chapter{Brief Tour of the Standard Library \label{briefTour}} |
| 4402 | |
| 4403 | |
| 4404 | \section{Operating System Interface\label{os-interface}} |
| 4405 | |
| 4406 | The \ulink{\module{os}}{../lib/module-os.html} |
| 4407 | module provides dozens of functions for interacting with the |
| 4408 | operating system: |
| 4409 | |
| 4410 | \begin{verbatim} |
| 4411 | >>> import os |
Raymond Hettinger | b7a10d1 | 2003-12-06 20:12:00 +0000 | [diff] [blame] | 4412 | >>> os.system('time 0:02') |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4413 | 0 |
| 4414 | >>> os.getcwd() # Return the current working directory |
| 4415 | 'C:\\Python24' |
| 4416 | >>> os.chdir('/server/accesslogs') |
| 4417 | \end{verbatim} |
| 4418 | |
| 4419 | Be sure to use the \samp{import os} style instead of |
| 4420 | \samp{from os import *}. This will keep \function{os.open()} from |
| 4421 | shadowing the builtin \function{open()} function which operates much |
| 4422 | differently. |
| 4423 | |
| 4424 | The builtin \function{dir()} and \function{help()} functions are useful |
| 4425 | as interactive aids for working with large modules like \module{os}: |
| 4426 | |
| 4427 | \begin{verbatim} |
| 4428 | >>> import os |
| 4429 | >>> dir(os) |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4430 | <returns a list of all module functions> |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4431 | >>> help(os) |
| 4432 | <returns an extensive manual page created from the module's docstrings> |
| 4433 | \end{verbatim} |
| 4434 | |
| 4435 | For daily file and directory management tasks, the |
| 4436 | \ulink{\module{shutil}}{../lib/module-shutil.html} |
| 4437 | module provides a higher level interface that is easier to use: |
| 4438 | |
| 4439 | \begin{verbatim} |
| 4440 | >>> import shutil |
| 4441 | >>> shutil.copyfile('data.db', 'archive.db') |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4442 | >>> shutil.move('/build/executables', 'installdir') |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4443 | \end{verbatim} |
| 4444 | |
| 4445 | |
| 4446 | \section{File Wildcards\label{file-wildcards}} |
| 4447 | |
| 4448 | The \ulink{\module{glob}}{../lib/module-glob.html} |
| 4449 | module provides a function for making file lists from directory |
| 4450 | wildcard searches: |
| 4451 | |
| 4452 | \begin{verbatim} |
| 4453 | >>> import glob |
| 4454 | >>> glob.glob('*.py') |
| 4455 | ['primes.py', 'random.py', 'quote.py'] |
| 4456 | \end{verbatim} |
| 4457 | |
| 4458 | |
| 4459 | \section{Command Line Arguments\label{command-line-arguments}} |
| 4460 | |
| 4461 | Common utility scripts often invoke processing command line arguments. |
| 4462 | These arguments are stored in the |
| 4463 | \ulink{\module{sys}}{../lib/module-sys.html}\ module's \var{argv} |
| 4464 | attribute as a list. For instance the following output results from |
| 4465 | running \samp{python demo.py one two three} at the command line: |
| 4466 | |
| 4467 | \begin{verbatim} |
| 4468 | >>> import sys |
Raymond Hettinger | ec3402f | 2003-12-05 06:39:54 +0000 | [diff] [blame] | 4469 | >>> print sys.argv |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4470 | ['demo.py', 'one', 'two', 'three'] |
| 4471 | \end{verbatim} |
| 4472 | |
| 4473 | The \ulink{\module{getopt}}{../lib/module-getopt.html} |
| 4474 | module processes \var{sys.argv} using the conventions of the \UNIX{} |
| 4475 | \function{getopt()} function. More powerful and flexible command line |
| 4476 | processing is provided by the |
| 4477 | \ulink{\module{optparse}}{../lib/module-optparse.html} module. |
| 4478 | |
| 4479 | |
| 4480 | \section{Error Output Redirection and Program Termination\label{stderr}} |
| 4481 | |
| 4482 | The \ulink{\module{sys}}{../lib/module-sys.html} |
| 4483 | module also has attributes for \var{stdin}, \var{stdout}, and |
| 4484 | \var{stderr}. The latter is useful for emitting warnings and error |
| 4485 | messages to make them visible even when \var{stdout} has been redirected: |
| 4486 | |
| 4487 | \begin{verbatim} |
| 4488 | >>> sys.stderr.write('Warning, log file not found starting a new one') |
| 4489 | Warning, log file not found starting a new one |
| 4490 | \end{verbatim} |
| 4491 | |
| 4492 | The most direct way to terminate a script is to use \samp{sys.exit()}. |
| 4493 | |
| 4494 | |
| 4495 | \section{String Pattern Matching\label{string-pattern-matching}} |
| 4496 | |
| 4497 | The \ulink{\module{re}}{../lib/module-re.html} |
| 4498 | module provides regular expression tools for advanced string processing. |
Raymond Hettinger | b7a10d1 | 2003-12-06 20:12:00 +0000 | [diff] [blame] | 4499 | For complex matching and manipulation, regular expressions offer succinct, |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4500 | optimized solutions: |
| 4501 | |
| 4502 | \begin{verbatim} |
| 4503 | >>> import re |
| 4504 | >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') |
| 4505 | ['foot', 'fell', 'fastest'] |
| 4506 | >>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat') |
| 4507 | 'cat in the hat' |
| 4508 | \end{verbatim} |
| 4509 | |
Raymond Hettinger | b7a10d1 | 2003-12-06 20:12:00 +0000 | [diff] [blame] | 4510 | When only simple capabilities are needed, string methods are preferred |
| 4511 | because they are easier to read and debug: |
| 4512 | |
| 4513 | \begin{verbatim} |
| 4514 | >>> 'tea for too'.replace('too', 'two') |
| 4515 | 'tea for two' |
| 4516 | \end{verbatim} |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4517 | |
| 4518 | \section{Mathematics\label{mathematics}} |
| 4519 | |
Raymond Hettinger | ec3402f | 2003-12-05 06:39:54 +0000 | [diff] [blame] | 4520 | The \ulink{\module{math}}{../lib/module-math.html} module gives |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4521 | access to the underlying C library functions for floating point math: |
| 4522 | |
| 4523 | \begin{verbatim} |
| 4524 | >>> import math |
| 4525 | >>> math.cos(math.pi / 4.0) |
| 4526 | 0.70710678118654757 |
| 4527 | >>> math.log(1024, 2) |
| 4528 | 10.0 |
| 4529 | \end{verbatim} |
| 4530 | |
| 4531 | The \ulink{\module{random}}{../lib/module-random.html} |
| 4532 | module provides tools for making random selections: |
| 4533 | |
| 4534 | \begin{verbatim} |
| 4535 | >>> import random |
| 4536 | >>> random.choice(['apple', 'pear', 'banana']) |
| 4537 | 'apple' |
| 4538 | >>> random.sample(xrange(100), 10) # sampling without replacement |
| 4539 | [30, 83, 16, 4, 8, 81, 41, 50, 18, 33] |
| 4540 | >>> random.random() # random float |
| 4541 | 0.17970987693706186 |
| 4542 | >>> random.randrange(6) # random integer chosen from range(6) |
| 4543 | 4 |
| 4544 | \end{verbatim} |
| 4545 | |
| 4546 | |
| 4547 | \section{Internet Access\label{internet-access}} |
| 4548 | |
| 4549 | There are a number of modules for accessing the internet and processing |
| 4550 | internet protocols. Two of the simplest are |
| 4551 | \ulink{\module{urllib2}}{../lib/module-urllib2.html} |
| 4552 | for retrieving data from urls and |
| 4553 | \ulink{\module{smtplib}}{../lib/module-smtplib.html} |
| 4554 | for sending mail: |
| 4555 | |
| 4556 | \begin{verbatim} |
| 4557 | >>> import urllib2 |
| 4558 | >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): |
| 4559 | ... if 'EST' in line: # look for Eastern Standard Time |
| 4560 | ... print line |
| 4561 | |
| 4562 | <BR>Nov. 25, 09:43:32 PM EST |
| 4563 | |
| 4564 | >>> import smtplib |
| 4565 | >>> server = smtplib.SMTP('localhost') |
| 4566 | >>> server.sendmail('soothsayer@tmp.org', 'jceasar@tmp.org', |
| 4567 | """To: jceasar@tmp.org |
| 4568 | From: soothsayer@tmp.org |
| 4569 | |
| 4570 | Beware the Ides of March. |
| 4571 | """) |
| 4572 | >>> server.quit() |
| 4573 | \end{verbatim} |
| 4574 | |
| 4575 | |
| 4576 | \section{Dates and Times\label{dates-and-times}} |
| 4577 | |
| 4578 | The \ulink{\module{datetime}}{../lib/module-datetime.html} module |
| 4579 | supplies classes for manipulating dates and times in both simple |
| 4580 | and complex ways. While date and time arithmetic is supported, the |
| 4581 | focus of the implementation is on efficient member extraction for |
| 4582 | output formatting and manipulation. The module also supports objects |
| 4583 | that are time zone aware. |
| 4584 | |
| 4585 | \begin{verbatim} |
| 4586 | # dates are easily constructed and formatted |
| 4587 | >>> from datetime import date |
| 4588 | >>> now = date.today() |
| 4589 | >>> now |
| 4590 | datetime.date(2003, 12, 2) |
| 4591 | >>> now.strftime("%m-%d-%y or %d%b %Y is a %A on the %d day of %B") |
| 4592 | '12-02-03 or 02Dec 2003 is a Tuesday on the 02 day of December' |
| 4593 | |
| 4594 | # dates support calendar arithmetic |
| 4595 | >>> birthday = date(1964, 7, 31) |
| 4596 | >>> age = now - birthday |
| 4597 | >>> age.days |
| 4598 | 14368 |
| 4599 | \end{verbatim} |
| 4600 | |
| 4601 | |
| 4602 | \section{Data Compression\label{data-compression}} |
| 4603 | |
| 4604 | Common data archiving and compression formats are directly supported |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4605 | by modules including: |
| 4606 | \ulink{\module{zlib}}{../lib/module-zlib.html}, |
| 4607 | \ulink{\module{gzip}}{../lib/module-gzip.html}, |
| 4608 | \ulink{\module{bz2}}{../lib/module-bz2.html}, |
| 4609 | \ulink{\module{zipfile}}{../lib/module-zipfile.html}, and |
| 4610 | \ulink{\module{tarfile}}{../lib/module-tarfile.html}. |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4611 | |
| 4612 | \begin{verbatim} |
| 4613 | >>> import zlib |
| 4614 | >>> s = 'witch which has which witches wrist watch' |
| 4615 | >>> len(s) |
| 4616 | 41 |
| 4617 | >>> t = zlib.compress(s) |
| 4618 | >>> len(t) |
| 4619 | 37 |
| 4620 | >>> zlib.decompress(t) |
| 4621 | 'witch which has which witches wrist watch' |
| 4622 | >>> zlib.crc32(t) |
| 4623 | -1438085031 |
| 4624 | \end{verbatim} |
| 4625 | |
| 4626 | |
| 4627 | \section{Performance Measurement\label{performance-measurement}} |
| 4628 | |
| 4629 | Some Python users develop a deep interest in knowing the relative |
| 4630 | performance between different approaches to the same problem. |
| 4631 | Python provides a measurement tool that answers those questions |
| 4632 | immediately. |
| 4633 | |
| 4634 | For example, it may be tempting to use the tuple packing and unpacking |
| 4635 | feature instead of the traditional approach to swapping arguments. |
| 4636 | The \ulink{\module{timeit}}{../lib/module-timeit.html} module |
| 4637 | quickly demonstrates that the traditional approach is faster: |
| 4638 | |
| 4639 | \begin{verbatim} |
| 4640 | >>> from timeit import Timer |
Raymond Hettinger | ec3402f | 2003-12-05 06:39:54 +0000 | [diff] [blame] | 4641 | >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4642 | 0.60864915603680925 |
Raymond Hettinger | ec3402f | 2003-12-05 06:39:54 +0000 | [diff] [blame] | 4643 | >>> Timer('a,b = b,a', 'a=1; b=2').timeit() |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4644 | 0.8625194857439773 |
| 4645 | \end{verbatim} |
| 4646 | |
| 4647 | In contrast to \module{timeit}'s fine level of granularity, the |
Raymond Hettinger | 8850c87 | 2003-12-03 22:33:13 +0000 | [diff] [blame] | 4648 | \ulink{\module{profile}}{../lib/module-profile.html} and \module{pstats} |
| 4649 | modules provide tools for identifying time critical sections in larger |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4650 | blocks of code. |
| 4651 | |
| 4652 | |
| 4653 | \section{Quality Control\label{quality-control}} |
| 4654 | |
| 4655 | One approach for developing high quality software is to write tests for |
| 4656 | each function as it is developed and to run those tests frequently during |
| 4657 | the development process. |
| 4658 | |
| 4659 | The \ulink{\module{doctest}}{../lib/module-doctest.html} module provides |
| 4660 | a tool for scanning a module and validating tests embedded in a program's |
| 4661 | docstrings. Test construction is as simple as cutting-and-pasting a |
| 4662 | typical call along with its results into the docstring. This improves |
| 4663 | the documentation by providing the user with an example and it allows the |
| 4664 | doctest module to make sure the code remains true to the documentation: |
| 4665 | |
| 4666 | \begin{verbatim} |
| 4667 | def average(values): |
| 4668 | """Computes the arithmetic mean of a list of numbers. |
| 4669 | |
| 4670 | >>> print average([20, 30, 70]) |
| 4671 | 40.0 |
| 4672 | """ |
| 4673 | return sum(values, 0.0) / len(values) |
| 4674 | |
| 4675 | import doctest |
| 4676 | doctest.testmod() # automatically validate the embedded tests |
| 4677 | \end{verbatim} |
| 4678 | |
| 4679 | The \ulink{\module{unittest}}{../lib/module-unittest.html} module is not |
| 4680 | as effortless as the \module{doctest} module, but it allows a more |
| 4681 | comprehensive set of tests to be maintained in a separate file: |
| 4682 | |
| 4683 | \begin{verbatim} |
| 4684 | import unittest |
| 4685 | |
| 4686 | class TestStatisticalFunctions(unittest.TestCase): |
| 4687 | |
| 4688 | def test_average(self): |
| 4689 | self.assertEqual(average([20, 30, 70]), 40.0) |
| 4690 | self.assertEqual(round(average([1, 5, 7]), 1), 4.3) |
| 4691 | self.assertRaises(ZeroDivisionError, average, []) |
| 4692 | self.assertRaises(TypeError, average, 20, 30, 70) |
| 4693 | |
| 4694 | unittest.main() # Calling from the command line invokes all tests |
| 4695 | \end{verbatim} |
| 4696 | |
| 4697 | \section{Batteries Included\label{batteries-included}} |
| 4698 | |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4699 | Python has a ``batteries included'' philosophy. This is best seen |
| 4700 | through the sophisticated and robust capabilities of its larger |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4701 | packages. For example: |
| 4702 | |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4703 | * The \ulink{\module{xmlrpclib}}{../lib/module-xmlrpclib.html} and |
| 4704 | \ulink{\module{SimpleXMLRPCServer}}{../lib/module-SimpleXMLRPCServer.html} |
| 4705 | modules make implementing remote procedure calls into an almost trivial |
| 4706 | task. Despite the names, no direct knowledge or handling of XML is needed. |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4707 | |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4708 | * The \ulink{\module{email}}{../lib/module-email.html} |
| 4709 | package is a library for managing email messages, |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4710 | including MIME and other RFC 2822-based message documents. Unlike |
| 4711 | \module{smtplib} and \module{poplib} which actually send and receive |
| 4712 | messages, the email package has a complete toolset for building or |
| 4713 | decoding complex message structures (including attachments) |
| 4714 | and for implementing internet encoding and header protocols. |
| 4715 | |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4716 | * The \ulink{\module{xml.dom}}{../lib/module-xml.dom.html} and |
| 4717 | \ulink{\module{xml.sax}}{../lib/module-xml.sax.html} packages provide |
| 4718 | robust support for parsing this popular data interchange format. Likewise, |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4719 | the \module{csv} module supports direct reads and writes in a common |
| 4720 | database format. Together, these modules and packages greatly simplify |
| 4721 | data interchange between python applications and other tools. |
| 4722 | |
| 4723 | * Internationalization is supported by a number of modules including |
Raymond Hettinger | f62444a | 2003-12-05 07:53:50 +0000 | [diff] [blame] | 4724 | \ulink{\module{gettext}}{../lib/module-gettext.html}, |
| 4725 | \ulink{\module{locale}}{../lib/module-locale.html}, and the |
| 4726 | \ulink{\module{codecs}}{../lib/module-codecs.html} package. |
Raymond Hettinger | 8772d4e | 2003-12-03 22:23:46 +0000 | [diff] [blame] | 4727 | |
| 4728 | |
| 4729 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4730 | \chapter{What Now? \label{whatNow}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4731 | |
Fred Drake | 979d041 | 2001-04-03 17:41:56 +0000 | [diff] [blame] | 4732 | Reading this tutorial has probably reinforced your interest in using |
| 4733 | Python --- you should be eager to apply Python to solve your |
| 4734 | real-world problems. Now what should you do? |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4735 | |
Fred Drake | 979d041 | 2001-04-03 17:41:56 +0000 | [diff] [blame] | 4736 | You should read, or at least page through, the |
| 4737 | \citetitle[../lib/lib.html]{Python Library Reference}, |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4738 | which gives complete (though terse) reference material about types, |
| 4739 | functions, and modules that can save you a lot of time when writing |
| 4740 | Python programs. The standard Python distribution includes a |
Fred Drake | ee84d59 | 1999-03-10 17:25:30 +0000 | [diff] [blame] | 4741 | \emph{lot} of code in both C and Python; there are modules to read |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4742 | \UNIX{} mailboxes, retrieve documents via HTTP, generate random |
| 4743 | numbers, parse command-line options, write CGI programs, compress |
| 4744 | data, and a lot more; skimming through the Library Reference will give |
| 4745 | you an idea of what's available. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4746 | |
Fred Drake | 518e55c | 2000-07-27 20:55:12 +0000 | [diff] [blame] | 4747 | The major Python Web site is \url{http://www.python.org/}; it contains |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4748 | code, documentation, and pointers to Python-related pages around the |
Fred Drake | 17f690f | 2001-07-14 02:14:42 +0000 | [diff] [blame] | 4749 | Web. This Web site is mirrored in various places around the |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4750 | world, such as Europe, Japan, and Australia; a mirror may be faster |
| 4751 | than the main site, depending on your geographical location. A more |
Fred Drake | c0fcbc1 | 1999-04-29 02:30:04 +0000 | [diff] [blame] | 4752 | informal site is \url{http://starship.python.net/}, which contains a |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4753 | bunch of Python-related personal home pages; many people have |
Raymond Hettinger | 8ee0060 | 2003-07-01 06:19:34 +0000 | [diff] [blame] | 4754 | downloadable software there. Many more user-created Python modules |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 4755 | can be found in the \ulink{Python Package |
| 4756 | Index}{http://www.python.org/pypi} (PyPI). |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4757 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4758 | For Python-related questions and problem reports, you can post to the |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 4759 | newsgroup \newsgroup{comp.lang.python}, or send them to the mailing |
Fred Drake | 518e55c | 2000-07-27 20:55:12 +0000 | [diff] [blame] | 4760 | list at \email{python-list@python.org}. The newsgroup and mailing list |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 4761 | are gatewayed, so messages posted to one will automatically be |
Raymond Hettinger | 8ee0060 | 2003-07-01 06:19:34 +0000 | [diff] [blame] | 4762 | forwarded to the other. There are around 120 postings a day (with peaks |
| 4763 | up to several hundred), |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 4764 | % Postings figure based on average of last six months activity as |
Fred Drake | 518e55c | 2000-07-27 20:55:12 +0000 | [diff] [blame] | 4765 | % reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182 |
| 4766 | % days = 116.9 msgs / day and steadily increasing. |
Fred Drake | 391564f | 1998-04-01 23:11:56 +0000 | [diff] [blame] | 4767 | asking (and answering) questions, suggesting new features, and |
| 4768 | announcing new modules. Before posting, be sure to check the list of |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 4769 | \ulink{Frequently Asked Questions}{http://www.python.org/doc/faq/} (also called the FAQ), or look for it in the |
Fred Drake | 518e55c | 2000-07-27 20:55:12 +0000 | [diff] [blame] | 4770 | \file{Misc/} directory of the Python source distribution. Mailing |
| 4771 | list archives are available at \url{http://www.python.org/pipermail/}. |
| 4772 | The FAQ answers many of the questions that come up again and again, |
| 4773 | and may already contain the solution for your problem. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4774 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4775 | |
Fred Drake | a594baf | 1998-04-03 05:16:31 +0000 | [diff] [blame] | 4776 | \appendix |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4777 | |
Fred Drake | d0c7137 | 2002-10-28 19:28:22 +0000 | [diff] [blame] | 4778 | \chapter{Interactive Input Editing and History Substitution\label{interacting}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4779 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4780 | Some versions of the Python interpreter support editing of the current |
| 4781 | input line and history substitution, similar to facilities found in |
| 4782 | the Korn shell and the GNU Bash shell. This is implemented using the |
Fred Drake | eee08cd | 1997-12-04 15:43:15 +0000 | [diff] [blame] | 4783 | \emph{GNU Readline} library, which supports Emacs-style and vi-style |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4784 | editing. This library has its own documentation which I won't |
Fred Drake | cc09e8d | 1998-12-28 21:21:36 +0000 | [diff] [blame] | 4785 | duplicate here; however, the basics are easily explained. The |
| 4786 | interactive editing and history described here are optionally |
| 4787 | available in the \UNIX{} and CygWin versions of the interpreter. |
| 4788 | |
| 4789 | This chapter does \emph{not} document the editing facilities of Mark |
| 4790 | Hammond's PythonWin package or the Tk-based environment, IDLE, |
| 4791 | distributed with Python. The command line history recall which |
| 4792 | operates within DOS boxes on NT and some other DOS and Windows flavors |
| 4793 | is yet another beast. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4794 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4795 | \section{Line Editing \label{lineEditing}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4796 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4797 | If supported, input line editing is active whenever the interpreter |
| 4798 | prints a primary or secondary prompt. The current line can be edited |
| 4799 | using the conventional Emacs control characters. The most important |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4800 | of these are: \kbd{C-A} (Control-A) moves the cursor to the beginning |
| 4801 | of the line, \kbd{C-E} to the end, \kbd{C-B} moves it one position to |
| 4802 | the left, \kbd{C-F} to the right. Backspace erases the character to |
| 4803 | the left of the cursor, \kbd{C-D} the character to its right. |
| 4804 | \kbd{C-K} kills (erases) the rest of the line to the right of the |
| 4805 | cursor, \kbd{C-Y} yanks back the last killed string. |
| 4806 | \kbd{C-underscore} undoes the last change you made; it can be repeated |
| 4807 | for cumulative effect. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4808 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4809 | \section{History Substitution \label{history}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4810 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4811 | History substitution works as follows. All non-empty input lines |
| 4812 | issued are saved in a history buffer, and when a new prompt is given |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4813 | you are positioned on a new line at the bottom of this buffer. |
| 4814 | \kbd{C-P} moves one line up (back) in the history buffer, |
| 4815 | \kbd{C-N} moves one down. Any line in the history buffer can be |
| 4816 | edited; an asterisk appears in front of the prompt to mark a line as |
| 4817 | modified. Pressing the \kbd{Return} key passes the current line to |
| 4818 | the interpreter. \kbd{C-R} starts an incremental reverse search; |
| 4819 | \kbd{C-S} starts a forward search. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4820 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4821 | \section{Key Bindings \label{keyBindings}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4822 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4823 | The key bindings and some other parameters of the Readline library can |
| 4824 | be customized by placing commands in an initialization file called |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4825 | \file{\~{}/.inputrc}. Key bindings have the form |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4826 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4827 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4828 | key-name: function-name |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4829 | \end{verbatim} |
| 4830 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4831 | or |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4832 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4833 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4834 | "string": function-name |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4835 | \end{verbatim} |
| 4836 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4837 | and options can be set with |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4838 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4839 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4840 | set option-name value |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4841 | \end{verbatim} |
| 4842 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4843 | For example: |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4844 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4845 | \begin{verbatim} |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4846 | # I prefer vi-style editing: |
| 4847 | set editing-mode vi |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4848 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4849 | # Edit using a single line: |
| 4850 | set horizontal-scroll-mode On |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4851 | |
Guido van Rossum | 0245569 | 1997-07-17 16:21:52 +0000 | [diff] [blame] | 4852 | # Rebind some keys: |
| 4853 | Meta-h: backward-kill-word |
| 4854 | "\C-u": universal-argument |
| 4855 | "\C-x\C-r": re-read-init-file |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4856 | \end{verbatim} |
| 4857 | |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4858 | Note that the default binding for \kbd{Tab} in Python is to insert a |
| 4859 | \kbd{Tab} character instead of Readline's default filename completion |
| 4860 | function. If you insist, you can override this by putting |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4861 | |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4862 | \begin{verbatim} |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4863 | Tab: complete |
Fred Drake | 8842e86 | 1998-02-13 07:16:30 +0000 | [diff] [blame] | 4864 | \end{verbatim} |
| 4865 | |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4866 | in your \file{\~{}/.inputrc}. (Of course, this makes it harder to |
Fred Drake | f5c87c4 | 2003-09-11 06:06:26 +0000 | [diff] [blame] | 4867 | type indented continuation lines if you're accustomed to using |
| 4868 | \kbd{Tab} for that purpose.) |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4869 | |
Fred Drake | 7238988 | 1998-04-13 01:31:10 +0000 | [diff] [blame] | 4870 | Automatic completion of variable and module names is optionally |
| 4871 | available. To enable it in the interpreter's interactive mode, add |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4872 | the following to your startup file:\footnote{ |
| 4873 | Python will execute the contents of a file identified by the |
| 4874 | \envvar{PYTHONSTARTUP} environment variable when you start an |
| 4875 | interactive interpreter.} |
Fred Drake | 20082d9 | 2000-04-03 04:26:58 +0000 | [diff] [blame] | 4876 | \refstmodindex{rlcompleter}\refbimodindex{readline} |
Fred Drake | 7238988 | 1998-04-13 01:31:10 +0000 | [diff] [blame] | 4877 | |
| 4878 | \begin{verbatim} |
| 4879 | import rlcompleter, readline |
| 4880 | readline.parse_and_bind('tab: complete') |
| 4881 | \end{verbatim} |
| 4882 | |
Fred Drake | 0181552 | 2001-07-18 19:21:12 +0000 | [diff] [blame] | 4883 | This binds the \kbd{Tab} key to the completion function, so hitting |
| 4884 | the \kbd{Tab} key twice suggests completions; it looks at Python |
| 4885 | statement names, the current local variables, and the available module |
| 4886 | names. For dotted expressions such as \code{string.a}, it will |
Raymond Hettinger | c7a2656 | 2003-08-12 00:01:17 +0000 | [diff] [blame] | 4887 | evaluate the expression up to the final \character{.} and then |
Fred Drake | 0181552 | 2001-07-18 19:21:12 +0000 | [diff] [blame] | 4888 | suggest completions from the attributes of the resulting object. Note |
| 4889 | that this may execute application-defined code if an object with a |
Fred Drake | 7238988 | 1998-04-13 01:31:10 +0000 | [diff] [blame] | 4890 | \method{__getattr__()} method is part of the expression. |
| 4891 | |
Fred Drake | 0181552 | 2001-07-18 19:21:12 +0000 | [diff] [blame] | 4892 | A more capable startup file might look like this example. Note that |
| 4893 | this deletes the names it creates once they are no longer needed; this |
| 4894 | is done since the startup file is executed in the same namespace as |
| 4895 | the interactive commands, and removing the names avoids creating side |
| 4896 | effects in the interactive environments. You may find it convenient |
Fred Drake | 626d472 | 2003-09-11 04:28:13 +0000 | [diff] [blame] | 4897 | to keep some of the imported modules, such as |
| 4898 | \ulink{\module{os}}{../lib/module-os.html}, which turn |
Fred Drake | 0181552 | 2001-07-18 19:21:12 +0000 | [diff] [blame] | 4899 | out to be needed in most sessions with the interpreter. |
| 4900 | |
| 4901 | \begin{verbatim} |
| 4902 | # Add auto-completion and a stored history file of commands to your Python |
| 4903 | # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is |
| 4904 | # bound to the Esc key by default (you can change it - see readline docs). |
| 4905 | # |
| 4906 | # Store the file in ~/.pystartup, and set an environment variable to point |
Raymond Hettinger | fa6cce1 | 2003-07-11 18:58:11 +0000 | [diff] [blame] | 4907 | # to it: "export PYTHONSTARTUP=/max/home/itamar/.pystartup" in bash. |
Fred Drake | 0181552 | 2001-07-18 19:21:12 +0000 | [diff] [blame] | 4908 | # |
| 4909 | # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the |
| 4910 | # full path to your home directory. |
| 4911 | |
| 4912 | import atexit |
| 4913 | import os |
| 4914 | import readline |
| 4915 | import rlcompleter |
| 4916 | |
| 4917 | historyPath = os.path.expanduser("~/.pyhistory") |
| 4918 | |
| 4919 | def save_history(historyPath=historyPath): |
| 4920 | import readline |
| 4921 | readline.write_history_file(historyPath) |
| 4922 | |
| 4923 | if os.path.exists(historyPath): |
| 4924 | readline.read_history_file(historyPath) |
| 4925 | |
| 4926 | atexit.register(save_history) |
| 4927 | del os, atexit, readline, rlcompleter, save_history, historyPath |
| 4928 | \end{verbatim} |
| 4929 | |
Fred Drake | 7238988 | 1998-04-13 01:31:10 +0000 | [diff] [blame] | 4930 | |
Fred Drake | b7833d3 | 1998-09-11 16:21:55 +0000 | [diff] [blame] | 4931 | \section{Commentary \label{commentary}} |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4932 | |
Fred Drake | 5443c49 | 2000-07-08 05:18:54 +0000 | [diff] [blame] | 4933 | This facility is an enormous step forward compared to earlier versions |
| 4934 | of the interpreter; however, some wishes are left: It would be nice if |
| 4935 | the proper indentation were suggested on continuation lines (the |
| 4936 | parser knows if an indent token is required next). The completion |
| 4937 | mechanism might use the interpreter's symbol table. A command to |
| 4938 | check (or even suggest) matching parentheses, quotes, etc., would also |
| 4939 | be useful. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 4940 | |
Guido van Rossum | 97662c8 | 1996-08-23 15:35:47 +0000 | [diff] [blame] | 4941 | |
Fred Drake | d0c7137 | 2002-10-28 19:28:22 +0000 | [diff] [blame] | 4942 | \chapter{Floating Point Arithmetic: Issues and Limitations\label{fp-issues}} |
Fred Drake | 4271310 | 2003-12-30 16:15:35 +0000 | [diff] [blame] | 4943 | \sectionauthor{Tim Peters}{tim_one@users.sourceforge.net} |
Fred Drake | 417d667 | 2001-06-08 16:24:58 +0000 | [diff] [blame] | 4944 | |
| 4945 | Floating-point numbers are represented in computer hardware as |
| 4946 | base 2 (binary) fractions. For example, the decimal fraction |
| 4947 | |
| 4948 | \begin{verbatim} |
| 4949 | 0.125 |
| 4950 | \end{verbatim} |
| 4951 | |
| 4952 | has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction |
| 4953 | |
| 4954 | \begin{verbatim} |
| 4955 | 0.001 |
| 4956 | \end{verbatim} |
| 4957 | |
| 4958 | has value 0/2 + 0/4 + 1/8. These two fractions have identical values, |
| 4959 | the only real difference being that the first is written in base 10 |
| 4960 | fractional notation, and the second in base 2. |
| 4961 | |
| 4962 | Unfortunately, most decimal fractions cannot be represented exactly as |
| 4963 | binary fractions. A consequence is that, in general, the decimal |
| 4964 | floating-point numbers you enter are only approximated by the binary |
| 4965 | floating-point numbers actually stored in the machine. |
| 4966 | |
| 4967 | The problem is easier to understand at first in base 10. Consider the |
| 4968 | fraction 1/3. You can approximate that as a base 10 fraction: |
| 4969 | |
| 4970 | \begin{verbatim} |
| 4971 | 0.3 |
| 4972 | \end{verbatim} |
| 4973 | |
| 4974 | or, better, |
| 4975 | |
| 4976 | \begin{verbatim} |
| 4977 | 0.33 |
| 4978 | \end{verbatim} |
| 4979 | |
| 4980 | or, better, |
| 4981 | |
| 4982 | \begin{verbatim} |
| 4983 | 0.333 |
| 4984 | \end{verbatim} |
| 4985 | |
| 4986 | and so on. No matter how many digits you're willing to write down, the |
| 4987 | result will never be exactly 1/3, but will be an increasingly better |
| 4988 | approximation to 1/3. |
| 4989 | |
| 4990 | In the same way, no matter how many base 2 digits you're willing to |
| 4991 | use, the decimal value 0.1 cannot be represented exactly as a base 2 |
| 4992 | fraction. In base 2, 1/10 is the infinitely repeating fraction |
| 4993 | |
| 4994 | \begin{verbatim} |
| 4995 | 0.0001100110011001100110011001100110011001100110011... |
| 4996 | \end{verbatim} |
| 4997 | |
| 4998 | Stop at any finite number of bits, and you get an approximation. This |
| 4999 | is why you see things like: |
| 5000 | |
| 5001 | \begin{verbatim} |
| 5002 | >>> 0.1 |
| 5003 | 0.10000000000000001 |
| 5004 | \end{verbatim} |
| 5005 | |
| 5006 | On most machines today, that is what you'll see if you enter 0.1 at |
| 5007 | a Python prompt. You may not, though, because the number of bits |
| 5008 | used by the hardware to store floating-point values can vary across |
| 5009 | machines, and Python only prints a decimal approximation to the true |
| 5010 | decimal value of the binary approximation stored by the machine. On |
| 5011 | most machines, if Python were to print the true decimal value of |
| 5012 | the binary approximation stored for 0.1, it would have to display |
| 5013 | |
| 5014 | \begin{verbatim} |
| 5015 | >>> 0.1 |
| 5016 | 0.1000000000000000055511151231257827021181583404541015625 |
| 5017 | \end{verbatim} |
| 5018 | |
| 5019 | instead! The Python prompt (implicitly) uses the builtin |
| 5020 | \function{repr()} function to obtain a string version of everything it |
| 5021 | displays. For floats, \code{repr(\var{float})} rounds the true |
| 5022 | decimal value to 17 significant digits, giving |
| 5023 | |
| 5024 | \begin{verbatim} |
| 5025 | 0.10000000000000001 |
| 5026 | \end{verbatim} |
| 5027 | |
| 5028 | \code{repr(\var{float})} produces 17 significant digits because it |
| 5029 | turns out that's enough (on most machines) so that |
| 5030 | \code{eval(repr(\var{x})) == \var{x}} exactly for all finite floats |
| 5031 | \var{x}, but rounding to 16 digits is not enough to make that true. |
| 5032 | |
| 5033 | Note that this is in the very nature of binary floating-point: this is |
| 5034 | not a bug in Python, it is not a bug in your code either, and you'll |
| 5035 | see the same kind of thing in all languages that support your |
Tim Peters | fa9e273 | 2001-06-17 21:57:17 +0000 | [diff] [blame] | 5036 | hardware's floating-point arithmetic (although some languages may |
| 5037 | not \emph{display} the difference by default, or in all output modes). |
Fred Drake | 417d667 | 2001-06-08 16:24:58 +0000 | [diff] [blame] | 5038 | |
| 5039 | Python's builtin \function{str()} function produces only 12 |
| 5040 | significant digits, and you may wish to use that instead. It's |
| 5041 | unusual for \code{eval(str(\var{x}))} to reproduce \var{x}, but the |
| 5042 | output may be more pleasant to look at: |
| 5043 | |
| 5044 | \begin{verbatim} |
| 5045 | >>> print str(0.1) |
| 5046 | 0.1 |
| 5047 | \end{verbatim} |
| 5048 | |
| 5049 | It's important to realize that this is, in a real sense, an illusion: |
| 5050 | the value in the machine is not exactly 1/10, you're simply rounding |
| 5051 | the \emph{display} of the true machine value. |
| 5052 | |
| 5053 | Other surprises follow from this one. For example, after seeing |
| 5054 | |
| 5055 | \begin{verbatim} |
| 5056 | >>> 0.1 |
| 5057 | 0.10000000000000001 |
| 5058 | \end{verbatim} |
| 5059 | |
| 5060 | you may be tempted to use the \function{round()} function to chop it |
| 5061 | back to the single digit you expect. But that makes no difference: |
| 5062 | |
| 5063 | \begin{verbatim} |
| 5064 | >>> round(0.1, 1) |
| 5065 | 0.10000000000000001 |
| 5066 | \end{verbatim} |
| 5067 | |
| 5068 | The problem is that the binary floating-point value stored for "0.1" |
| 5069 | was already the best possible binary approximation to 1/10, so trying |
| 5070 | to round it again can't make it better: it was already as good as it |
| 5071 | gets. |
| 5072 | |
| 5073 | Another consequence is that since 0.1 is not exactly 1/10, adding 0.1 |
| 5074 | to itself 10 times may not yield exactly 1.0, either: |
| 5075 | |
| 5076 | \begin{verbatim} |
| 5077 | >>> sum = 0.0 |
| 5078 | >>> for i in range(10): |
| 5079 | ... sum += 0.1 |
| 5080 | ... |
| 5081 | >>> sum |
| 5082 | 0.99999999999999989 |
| 5083 | \end{verbatim} |
| 5084 | |
| 5085 | Binary floating-point arithmetic holds many surprises like this. The |
| 5086 | problem with "0.1" is explained in precise detail below, in the |
| 5087 | "Representation Error" section. See |
| 5088 | \citetitle[http://www.lahey.com/float.htm]{The Perils of Floating |
| 5089 | Point} for a more complete account of other common surprises. |
| 5090 | |
| 5091 | As that says near the end, ``there are no easy answers.'' Still, |
| 5092 | don't be unduly wary of floating-point! The errors in Python float |
| 5093 | operations are inherited from the floating-point hardware, and on most |
| 5094 | machines are on the order of no more than 1 part in 2**53 per |
| 5095 | operation. That's more than adequate for most tasks, but you do need |
| 5096 | to keep in mind that it's not decimal arithmetic, and that every float |
| 5097 | operation can suffer a new rounding error. |
| 5098 | |
| 5099 | While pathological cases do exist, for most casual use of |
| 5100 | floating-point arithmetic you'll see the result you expect in the end |
| 5101 | if you simply round the display of your final results to the number of |
| 5102 | decimal digits you expect. \function{str()} usually suffices, and for |
| 5103 | finer control see the discussion of Pythons's \code{\%} format |
| 5104 | operator: the \code{\%g}, \code{\%f} and \code{\%e} format codes |
| 5105 | supply flexible and easy ways to round float results for display. |
| 5106 | |
| 5107 | |
| 5108 | \section{Representation Error |
| 5109 | \label{fp-error}} |
| 5110 | |
| 5111 | This section explains the ``0.1'' example in detail, and shows how |
| 5112 | you can perform an exact analysis of cases like this yourself. Basic |
| 5113 | familiarity with binary floating-point representation is assumed. |
| 5114 | |
| 5115 | \dfn{Representation error} refers to that some (most, actually) |
| 5116 | decimal fractions cannot be represented exactly as binary (base 2) |
| 5117 | fractions. This is the chief reason why Python (or Perl, C, \Cpp, |
| 5118 | Java, Fortran, and many others) often won't display the exact decimal |
| 5119 | number you expect: |
| 5120 | |
| 5121 | \begin{verbatim} |
| 5122 | >>> 0.1 |
| 5123 | 0.10000000000000001 |
| 5124 | \end{verbatim} |
| 5125 | |
| 5126 | Why is that? 1/10 is not exactly representable as a binary fraction. |
| 5127 | Almost all machines today (November 2000) use IEEE-754 floating point |
| 5128 | arithmetic, and almost all platforms map Python floats to IEEE-754 |
| 5129 | "double precision". 754 doubles contain 53 bits of precision, so on |
| 5130 | input the computer strives to convert 0.1 to the closest fraction it can |
| 5131 | of the form \var{J}/2**\var{N} where \var{J} is an integer containing |
| 5132 | exactly 53 bits. Rewriting |
| 5133 | |
| 5134 | \begin{verbatim} |
| 5135 | 1 / 10 ~= J / (2**N) |
| 5136 | \end{verbatim} |
| 5137 | |
| 5138 | as |
| 5139 | |
| 5140 | \begin{verbatim} |
| 5141 | J ~= 2**N / 10 |
| 5142 | \end{verbatim} |
| 5143 | |
| 5144 | and recalling that \var{J} has exactly 53 bits (is \code{>= 2**52} but |
| 5145 | \code{< 2**53}), the best value for \var{N} is 56: |
| 5146 | |
| 5147 | \begin{verbatim} |
| 5148 | >>> 2L**52 |
| 5149 | 4503599627370496L |
| 5150 | >>> 2L**53 |
| 5151 | 9007199254740992L |
| 5152 | >>> 2L**56/10 |
| 5153 | 7205759403792793L |
| 5154 | \end{verbatim} |
| 5155 | |
| 5156 | That is, 56 is the only value for \var{N} that leaves \var{J} with |
| 5157 | exactly 53 bits. The best possible value for \var{J} is then that |
| 5158 | quotient rounded: |
| 5159 | |
| 5160 | \begin{verbatim} |
| 5161 | >>> q, r = divmod(2L**56, 10) |
| 5162 | >>> r |
| 5163 | 6L |
| 5164 | \end{verbatim} |
| 5165 | |
| 5166 | Since the remainder is more than half of 10, the best approximation is |
| 5167 | obtained by rounding up: |
| 5168 | |
| 5169 | \begin{verbatim} |
| 5170 | >>> q+1 |
| 5171 | 7205759403792794L |
| 5172 | \end{verbatim} |
| 5173 | |
| 5174 | Therefore the best possible approximation to 1/10 in 754 double |
| 5175 | precision is that over 2**56, or |
| 5176 | |
| 5177 | \begin{verbatim} |
| 5178 | 7205759403792794 / 72057594037927936 |
| 5179 | \end{verbatim} |
| 5180 | |
| 5181 | Note that since we rounded up, this is actually a little bit larger than |
| 5182 | 1/10; if we had not rounded up, the quotient would have been a little |
Tim Peters | fa9e273 | 2001-06-17 21:57:17 +0000 | [diff] [blame] | 5183 | bit smaller than 1/10. But in no case can it be \emph{exactly} 1/10! |
Fred Drake | 417d667 | 2001-06-08 16:24:58 +0000 | [diff] [blame] | 5184 | |
| 5185 | So the computer never ``sees'' 1/10: what it sees is the exact |
| 5186 | fraction given above, the best 754 double approximation it can get: |
| 5187 | |
| 5188 | \begin{verbatim} |
| 5189 | >>> .1 * 2L**56 |
| 5190 | 7205759403792794.0 |
| 5191 | \end{verbatim} |
| 5192 | |
| 5193 | If we multiply that fraction by 10**30, we can see the (truncated) |
| 5194 | value of its 30 most significant decimal digits: |
| 5195 | |
| 5196 | \begin{verbatim} |
| 5197 | >>> 7205759403792794L * 10L**30 / 2L**56 |
| 5198 | 100000000000000005551115123125L |
| 5199 | \end{verbatim} |
| 5200 | |
| 5201 | meaning that the exact number stored in the computer is approximately |
| 5202 | equal to the decimal value 0.100000000000000005551115123125. Rounding |
| 5203 | that to 17 significant digits gives the 0.10000000000000001 that Python |
| 5204 | displays (well, will display on any 754-conforming platform that does |
| 5205 | best-possible input and output conversions in its C library --- yours may |
| 5206 | not!). |
| 5207 | |
Fred Drake | d5df09c | 2001-06-20 21:37:34 +0000 | [diff] [blame] | 5208 | \chapter{History and License} |
| 5209 | \input{license} |
| 5210 | |
Skip Montanaro | 40d4bc5 | 2003-09-24 16:53:02 +0000 | [diff] [blame] | 5211 | \input{glossary} |
| 5212 | |
| 5213 | \input{tut.ind} |
| 5214 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 5215 | \end{document} |