Guido van Rossum | 3795378 | 1992-04-06 14:04:04 +0000 | [diff] [blame] | 1 | \documentstyle[twoside,11pt,myformat]{report} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3 | \title{Python Tutorial} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 4 | |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 5 | \input{boilerplate} |
Guido van Rossum | 83eb962 | 1993-11-23 16:28:45 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 7 | \begin{document} |
| 8 | |
| 9 | \pagenumbering{roman} |
| 10 | |
| 11 | \maketitle |
| 12 | |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 13 | \input{copyright} |
| 14 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 15 | \begin{abstract} |
| 16 | |
| 17 | \noindent |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 18 | Python is a simple, yet powerful programming language that bridges the |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 19 | gap between C and shell programming, and is thus ideally suited for |
| 20 | ``throw-away programming'' |
| 21 | and rapid prototyping. Its syntax is put |
| 22 | together from constructs borrowed from a variety of other languages; |
| 23 | most prominent are influences from ABC, C, Modula-3 and Icon. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 24 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 25 | The Python interpreter is easily extended with new functions and data |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 26 | types implemented in C. Python is also suitable as an extension |
| 27 | language for highly customizable C applications such as editors or |
| 28 | window managers. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 29 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 30 | Python is available for various operating systems, amongst which |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 31 | several flavors of {\UNIX}, Amoeba, the Apple Macintosh O.S., |
| 32 | and MS-DOS. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 33 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 34 | This tutorial introduces the reader informally to the basic concepts |
| 35 | and features of the Python language and system. It helps to have a |
| 36 | Python interpreter handy for hands-on experience, but as the examples |
| 37 | are self-contained, the tutorial can be read off-line as well. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 38 | |
Guido van Rossum | 481ae68 | 1991-11-25 17:28:03 +0000 | [diff] [blame] | 39 | For a description of standard objects and modules, see the {\em Python |
| 40 | Library Reference} document. The {\em Python Reference Manual} gives |
| 41 | a more formal definition of the language. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 42 | |
| 43 | \end{abstract} |
| 44 | |
| 45 | \pagebreak |
Guido van Rossum | cdc9355 | 1992-02-11 15:53:13 +0000 | [diff] [blame] | 46 | { |
| 47 | \parskip = 0mm |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 48 | \tableofcontents |
Guido van Rossum | cdc9355 | 1992-02-11 15:53:13 +0000 | [diff] [blame] | 49 | } |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 50 | |
| 51 | \pagebreak |
| 52 | |
| 53 | \pagenumbering{arabic} |
| 54 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 55 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 56 | \chapter{Whetting Your Appetite} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 57 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 58 | If you ever wrote a large shell script, you probably know this |
| 59 | feeling: you'd love to add yet another feature, but it's already so |
| 60 | slow, and so big, and so complicated; or the feature involves a system |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 61 | 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] | 62 | the problem at hand isn't serious enough to warrant rewriting the |
| 63 | script in C; perhaps because the problem requires variable-length |
| 64 | strings or other data types (like sorted lists of file names) that are |
| 65 | easy in the shell but lots of work to implement in C; or perhaps just |
| 66 | because you're not sufficiently familiar with C. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 67 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 68 | In such cases, Python may be just the language for you. Python is |
| 69 | simple to use, but it is a real programming language, offering much |
| 70 | more structure and support for large programs than the shell has. On |
| 71 | the other hand, it also offers much more error checking than C, and, |
| 72 | being a {\em very-high-level language}, it has high-level data types |
| 73 | built in, such as flexible arrays and dictionaries that would cost you |
| 74 | days to implement efficiently in C. Because of its more general data |
| 75 | types Python is applicable to a much larger problem domain than {\em |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 76 | Awk} or even {\em Perl}, yet many things are at least as easy in |
| 77 | Python as in those languages. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 78 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 79 | Python allows you to split up your program in modules that can be |
| 80 | 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] | 81 | standard modules that you can use as the basis of your programs --- or |
| 82 | as examples to start learning to program in Python. There are also |
| 83 | built-in modules that provide things like file I/O, system calls, |
| 84 | sockets, and even a generic interface to window systems (STDWIN). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 85 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 86 | Python is an interpreted language, which can save you considerable time |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 87 | during program development because no compilation and linking is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 88 | necessary. The interpreter can be used interactively, which makes it |
| 89 | easy to experiment with features of the language, to write throw-away |
| 90 | programs, or to test functions during bottom-up program development. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 91 | It is also a handy desk calculator. |
| 92 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 93 | Python allows writing very compact and readable programs. Programs |
| 94 | written in Python are typically much shorter than equivalent C |
| 95 | programs, for several reasons: |
| 96 | \begin{itemize} |
| 97 | \item |
| 98 | the high-level data types allow you to express complex operations in a |
| 99 | single statement; |
| 100 | \item |
| 101 | statement grouping is done by indentation instead of begin/end |
| 102 | brackets; |
| 103 | \item |
| 104 | no variable or argument declarations are necessary. |
| 105 | \end{itemize} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 106 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 107 | Python is {\em extensible}: if you know how to program in C it is easy |
| 108 | to add a new built-in |
| 109 | function or |
| 110 | module to the interpreter, either to |
| 111 | perform critical operations at maximum speed, or to link Python |
| 112 | programs to libraries that may only be available in binary form (such |
| 113 | as a vendor-specific graphics library). Once you are really hooked, |
| 114 | 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] | 115 | and use it as an extension or command language for that application. |
| 116 | |
| 117 | By the way, the language is named after the BBC show ``Monty |
| 118 | Python's Flying Circus'' and has nothing to do with nasty reptiles... |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 119 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 120 | \section{Where From Here} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 121 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 122 | 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] | 123 | 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] | 124 | using it, you are invited here to do so. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 125 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 126 | In the next chapter, the mechanics of using the interpreter are |
| 127 | explained. This is rather mundane information, but essential for |
| 128 | trying out the examples shown later. |
| 129 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 130 | The rest of the tutorial introduces various features of the Python |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 131 | language and system though examples, beginning with simple |
| 132 | expressions, statements and data types, through functions and modules, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 133 | and finally touching upon advanced concepts like exceptions |
| 134 | and user-defined classes. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 135 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 136 | When you're through with the tutorial (or just getting bored), you |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 137 | should read the Library Reference, which gives complete (though terse) |
| 138 | reference material about built-in and standard types, functions and |
| 139 | modules that can save you a lot of time when writing Python programs. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 140 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 141 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 142 | \chapter{Using the Python Interpreter} |
| 143 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 144 | \section{Invoking the Interpreter} |
| 145 | |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 146 | The Python interpreter is usually installed as {\tt /usr/local/bin/python} |
| 147 | on those machines where it is available; putting {\tt /usr/local/bin} in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 148 | your {\UNIX} shell's search path makes it possible to start it by |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 149 | typing the command |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 150 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 151 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 152 | python |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 153 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 154 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 155 | to the shell. Since the choice of the directory where the interpreter |
| 156 | lives is an installation option, other places are possible; check with |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 157 | your local Python guru or system administrator. (E.g., {\tt |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 158 | /usr/local/python} is a popular alternative location.) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 159 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 160 | The interpreter operates somewhat like the {\UNIX} shell: when called |
| 161 | with standard input connected to a tty device, it reads and executes |
| 162 | commands interactively; when called with a file name argument or with |
| 163 | a file as standard input, it reads and executes a {\em script} from |
| 164 | that file. |
| 165 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 166 | A third way of starting the interpreter is |
| 167 | ``{\tt python -c command [arg] ...}'', which |
| 168 | executes the statement(s) in {\tt command}, analogous to the shell's |
| 169 | {\tt -c} option. Since Python statements often contain spaces or other |
| 170 | characters that are special to the shell, it is best to quote {\tt |
| 171 | command} in its entirety with double quotes. |
| 172 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 173 | Note that there is a difference between ``{\tt python file}'' and |
| 174 | ``{\tt python $<$file}''. In the latter case, input requests from the |
Guido van Rossum | 573805a | 1992-03-06 10:56:03 +0000 | [diff] [blame] | 175 | program, such as calls to {\tt input()} and {\tt raw_input()}, are |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 176 | satisfied from {\em file}. Since this file has already been read |
| 177 | until the end by the parser before the program starts executing, the |
| 178 | program will encounter EOF immediately. In the former case (which is |
| 179 | usually what you want) they are satisfied from whatever file or device |
| 180 | is connected to standard input of the Python interpreter. |
| 181 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 182 | When a script file is used, it is sometimes useful to be able to run |
| 183 | the script and enter interactive mode afterwards. This can be done by |
| 184 | passing {\tt -i} before the script. (This does not work if the script |
| 185 | is read from standard input, for the same reason as explained in the |
| 186 | previous paragraph.) |
| 187 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 188 | \subsection{Argument Passing} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 189 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 190 | When known to the interpreter, the script name and additional |
| 191 | arguments thereafter are passed to the script in the variable {\tt |
| 192 | sys.argv}, which is a list of strings. Its length is at least one; |
| 193 | when no script and no arguments are given, {\tt sys.argv[0]} is an |
| 194 | empty string. When the script name is given as {\tt '-'} (meaning |
| 195 | standard input), {\tt sys.argv[0]} is set to {\tt '-'}. When {\tt -c |
| 196 | command} is used, {\tt sys.argv[0]} is set to {\tt '-c'}. Options |
| 197 | found after {\tt -c command} are not consumed by the Python |
| 198 | interpreter's option processing but left in {\tt sys.argv} for the |
| 199 | command to handle. |
| 200 | |
| 201 | \subsection{Interactive Mode} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 202 | |
Guido van Rossum | dd01080 | 1991-06-07 14:31:11 +0000 | [diff] [blame] | 203 | When commands are read from a tty, the interpreter is said to be in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 204 | {\em interactive\ mode}. In this mode it prompts for the next command |
| 205 | with the {\em primary\ prompt}, usually three greater-than signs ({\tt |
Guido van Rossum | a67dee3 | 1995-09-13 17:34:25 +0000 | [diff] [blame] | 206 | >>>}); for continuation lines it prompts with the |
| 207 | {\em secondary\ prompt}, |
Guido van Rossum | 34e1777 | 1996-06-10 19:44:49 +0000 | [diff] [blame^] | 208 | by default three dots ({\tt ...}). Typing an EOF character |
| 209 | (Control-D on {\UNIX}, Control-Z on DOS or Windows) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 210 | at the primary prompt causes the interpreter to exit with a zero exit |
| 211 | status. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 212 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 213 | The interpreter prints a welcome message stating its version number |
| 214 | and a copyright notice before printing the first prompt, e.g.: |
| 215 | |
| 216 | \bcode\begin{verbatim} |
| 217 | python |
Guido van Rossum | 288527a | 1995-10-09 21:02:17 +0000 | [diff] [blame] | 218 | Python 1.3 (Oct 13 1995) |
Guido van Rossum | 1133aec | 1995-03-15 11:34:18 +0000 | [diff] [blame] | 219 | Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 220 | >>> |
| 221 | \end{verbatim}\ecode |
| 222 | |
| 223 | \section{The Interpreter and its Environment} |
| 224 | |
| 225 | \subsection{Error Handling} |
| 226 | |
| 227 | When an error occurs, the interpreter prints an error |
| 228 | message and a stack trace. In interactive mode, it then returns to |
| 229 | the primary prompt; when input came from a file, it exits with a |
| 230 | nonzero exit status after printing |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 231 | the stack trace. (Exceptions handled by an {\tt except} clause in a |
| 232 | {\tt try} statement are not errors in this context.) Some errors are |
| 233 | unconditionally fatal and cause an exit with a nonzero exit; this |
| 234 | applies to internal inconsistencies and some cases of running out of |
| 235 | memory. All error messages are written to the standard error stream; |
| 236 | normal output from the executed commands is written to standard |
| 237 | output. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 238 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 239 | Typing the interrupt character (usually Control-C or DEL) to the |
| 240 | primary or secondary prompt cancels the input and returns to the |
| 241 | primary prompt.% |
| 242 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 243 | A problem with the GNU Readline package may prevent this. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 244 | } |
| 245 | Typing an interrupt while a command is executing raises the {\tt |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 246 | KeyboardInterrupt} exception, which may be handled by a {\tt try} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 247 | statement. |
| 248 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 249 | \subsection{The Module Search Path} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 250 | |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 251 | When a module named {\tt spam} is imported, the interpreter searches |
| 252 | for a file named {\tt spam.py} in the list of directories specified by |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 253 | the environment variable {\tt PYTHONPATH}. It has the same syntax as |
| 254 | the {\UNIX} shell variable {\tt PATH}, i.e., a list of colon-separated |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 255 | directory names. When {\tt PYTHONPATH} is not set, or when the file |
| 256 | is not found there, the search continues in an installation-dependent |
| 257 | default path, usually {\tt .:/usr/local/lib/python}. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 258 | |
| 259 | Actually, modules are searched in the list of directories given by the |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 260 | variable {\tt sys.path} which is initialized from {\tt PYTHONPATH} and |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 261 | the installation-dependent default. This allows Python programs that |
| 262 | know what they're doing to modify or replace the module search path. |
| 263 | See the section on Standard Modules later. |
| 264 | |
| 265 | \subsection{``Compiled'' Python files} |
| 266 | |
| 267 | As an important speed-up of the start-up time for short programs that |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 268 | use a lot of standard modules, if a file called {\tt spam.pyc} exists |
| 269 | in the directory where {\tt spam.py} is found, this is assumed to |
| 270 | contain an already-``compiled'' version of the module {\tt spam}. The |
| 271 | modification time of the version of {\tt spam.py} used to create {\tt |
| 272 | spam.pyc} is recorded in {\tt spam.pyc}, and the file is ignored if |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 273 | these don't match. |
| 274 | |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 275 | Whenever {\tt spam.py} is successfully compiled, an attempt is made to |
| 276 | write the compiled version to {\tt spam.pyc}. It is not an error if |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 277 | this attempt fails; if for any reason the file is not written |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 278 | completely, the resulting {\tt spam.pyc} file will be recognized as |
Guido van Rossum | 34e1777 | 1996-06-10 19:44:49 +0000 | [diff] [blame^] | 279 | invalid and thus ignored later. The contents of the {\tt spam.pyc} |
| 280 | file is platform independent, so a Python module directory can be |
| 281 | shared by machines of different architectures. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 282 | |
| 283 | \subsection{Executable Python scripts} |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 284 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 285 | On BSD'ish {\UNIX} systems, Python scripts can be made directly |
| 286 | executable, like shell scripts, by putting the line |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 287 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 288 | \bcode\begin{verbatim} |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 289 | #! /usr/local/bin/python |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 290 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 291 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 292 | (assuming that's the name of the interpreter) at the beginning of the |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 293 | script and giving the file an executable mode. The {\tt \#!} must be |
| 294 | the first two characters of the file. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 295 | |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 296 | \subsection{The Interactive Startup File} |
| 297 | |
| 298 | When you use Python interactively, it is frequently handy to have some |
| 299 | standard commands executed every time the interpreter is started. You |
| 300 | can do this by setting an environment variable named {\tt |
| 301 | PYTHONSTARTUP} to the name of a file containing your start-up |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 302 | commands. This is similar to the {\tt .profile} feature of the UNIX |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 303 | shells. |
| 304 | |
| 305 | This file is only read in interactive sessions, not when Python reads |
| 306 | commands from a script, and not when {\tt /dev/tty} is given as the |
| 307 | explicit source of commands (which otherwise behaves like an |
| 308 | interactive session). It is executed in the same name space where |
| 309 | interactive commands are executed, so that objects that it defines or |
| 310 | imports can be used without qualification in the interactive session. |
Guido van Rossum | 7b3c8a1 | 1992-09-08 09:20:13 +0000 | [diff] [blame] | 311 | You can also change the prompts {\tt sys.ps1} and {\tt sys.ps2} in |
| 312 | this file. |
Guido van Rossum | 9a4e3fc | 1992-09-03 21:27:55 +0000 | [diff] [blame] | 313 | |
| 314 | If you want to read an additional start-up file from the current |
| 315 | directory, you can program this in the global start-up file, e.g. |
| 316 | \verb\execfile('.pythonrc')\. If you want to use the startup file |
| 317 | in a script, you must write this explicitly in the script, e.g. |
| 318 | \verb\import os;\ \verb\execfile(os.environ['PYTHONSTARTUP'])\. |
| 319 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 320 | \section{Interactive Input Editing and History Substitution} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 321 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 322 | Some versions of the Python interpreter support editing of the current |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 323 | input line and history substitution, similar to facilities found in |
| 324 | the Korn shell and the GNU Bash shell. This is implemented using the |
| 325 | {\em GNU\ Readline} library, which supports Emacs-style and vi-style |
| 326 | editing. This library has its own documentation which I won't |
| 327 | duplicate here; however, the basics are easily explained. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 328 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 329 | Perhaps the quickest check to see whether command line editing is |
| 330 | supported is typing Control-P to the first Python prompt you get. If |
| 331 | it beeps, you have command line editing. If nothing appears to |
| 332 | happen, or if \verb/^P/ is echoed, you can skip the rest of this |
| 333 | section. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 334 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 335 | \subsection{Line Editing} |
| 336 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 337 | If supported, input line editing is active whenever the interpreter |
| 338 | prints a primary or secondary prompt. The current line can be edited |
| 339 | using the conventional Emacs control characters. The most important |
| 340 | of these are: C-A (Control-A) moves the cursor to the beginning of the |
| 341 | line, C-E to the end, C-B moves it one position to the left, C-F to |
| 342 | the right. Backspace erases the character to the left of the cursor, |
| 343 | C-D the character to its right. C-K kills (erases) the rest of the |
| 344 | line to the right of the cursor, C-Y yanks back the last killed |
| 345 | string. C-underscore undoes the last change you made; it can be |
| 346 | repeated for cumulative effect. |
| 347 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 348 | \subsection{History Substitution} |
| 349 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 350 | History substitution works as follows. All non-empty input lines |
| 351 | issued are saved in a history buffer, and when a new prompt is given |
| 352 | you are positioned on a new line at the bottom of this buffer. C-P |
| 353 | moves one line up (back) in the history buffer, C-N moves one down. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 354 | Any line in the history buffer can be edited; an asterisk appears in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 355 | front of the prompt to mark a line as modified. Pressing the Return |
| 356 | key passes the current line to the interpreter. C-R starts an |
| 357 | incremental reverse search; C-S starts a forward search. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 358 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 359 | \subsection{Key Bindings} |
| 360 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 361 | The key bindings and some other parameters of the Readline library can |
| 362 | be customized by placing commands in an initialization file called |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 363 | {\tt \$HOME/.inputrc}. Key bindings have the form |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 364 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 365 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 366 | key-name: function-name |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 367 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 368 | % |
| 369 | or |
| 370 | |
| 371 | \bcode\begin{verbatim} |
| 372 | "string": function-name |
| 373 | \end{verbatim}\ecode |
| 374 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 375 | and options can be set with |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 376 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 377 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 378 | set option-name value |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 379 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 380 | % |
| 381 | For example: |
| 382 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 383 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 384 | # I prefer vi-style editing: |
| 385 | set editing-mode vi |
| 386 | # Edit using a single line: |
| 387 | set horizontal-scroll-mode On |
| 388 | # Rebind some keys: |
| 389 | Meta-h: backward-kill-word |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 390 | "\C-u": universal-argument |
| 391 | "\C-x\C-r": re-read-init-file |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 392 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 393 | % |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 394 | Note that the default binding for TAB in Python is to insert a TAB |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 395 | instead of Readline's default filename completion function. If you |
| 396 | insist, you can override this by putting |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 397 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 398 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 399 | TAB: complete |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 400 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 401 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 402 | in your {\tt \$HOME/.inputrc}. (Of course, this makes it hard to type |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 403 | indented continuation lines...) |
| 404 | |
| 405 | \subsection{Commentary} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 406 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 407 | This facility is an enormous step forward compared to previous |
| 408 | versions of the interpreter; however, some wishes are left: It would |
| 409 | be nice if the proper indentation were suggested on continuation lines |
| 410 | (the parser knows if an indent token is required next). The |
| 411 | completion mechanism might use the interpreter's symbol table. A |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 412 | command to check (or even suggest) matching parentheses, quotes etc. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 413 | would also be useful. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 414 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 415 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 416 | \chapter{An Informal Introduction to Python} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 417 | |
| 418 | In the following examples, input and output are distinguished by the |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 419 | presence or absence of prompts ({\tt >>>} and {\tt ...}): to repeat |
| 420 | the example, you must type everything after the prompt, when the |
| 421 | prompt appears; lines that do not begin with a prompt are output from |
| 422 | the interpreter.% |
| 423 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 424 | I'd prefer to use different fonts to distinguish input |
| 425 | from output, but the amount of LaTeX hacking that would require |
| 426 | is currently beyond my ability. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 427 | } |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 428 | Note that a secondary prompt on a line by itself in an example means |
| 429 | 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] | 430 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 431 | \section{Using Python as a Calculator} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 432 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 433 | Let's try some simple Python commands. Start the interpreter and wait |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 434 | for the primary prompt, {\tt >>>}. (It shouldn't take long.) |
| 435 | |
| 436 | \subsection{Numbers} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 437 | |
| 438 | The interpreter acts as a simple calculator: you can type an |
| 439 | expression at it and it will write the value. Expression syntax is |
| 440 | straightforward: the operators {\tt +}, {\tt -}, {\tt *} and {\tt /} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 441 | work just like in most other languages (e.g., Pascal or C); parentheses |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 442 | can be used for grouping. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 443 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 444 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 445 | >>> 2+2 |
| 446 | 4 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 447 | >>> # This is a comment |
| 448 | ... 2+2 |
| 449 | 4 |
| 450 | >>> 2+2 # and a comment on the same line as code |
| 451 | 4 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 452 | >>> (50-5*6)/4 |
| 453 | 5 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 454 | >>> # Integer division returns the floor: |
| 455 | ... 7/3 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 456 | 2 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 457 | >>> 7/-3 |
| 458 | -3 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 459 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 460 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 461 | % |
| 462 | Like in C, the equal sign ({\tt =}) is used to assign a value to a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 463 | variable. The value of an assignment is not written: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 464 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 465 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 466 | >>> width = 20 |
| 467 | >>> height = 5*9 |
| 468 | >>> width * height |
| 469 | 900 |
| 470 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 471 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 472 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 473 | A value can be assigned to several variables simultaneously: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 474 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 475 | \bcode\begin{verbatim} |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 476 | >>> x = y = z = 0 # Zero x, y and z |
| 477 | >>> x |
| 478 | 0 |
| 479 | >>> y |
| 480 | 0 |
| 481 | >>> z |
| 482 | 0 |
| 483 | >>> |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 484 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 485 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 486 | There is full support for floating point; operators with mixed type |
| 487 | operands convert the integer operand to floating point: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 488 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 489 | \bcode\begin{verbatim} |
| 490 | >>> 4 * 2.5 / 3.3 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 491 | 3.0303030303 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 492 | >>> 7.0 / 2 |
| 493 | 3.5 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 494 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 495 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 496 | |
| 497 | \subsection{Strings} |
| 498 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 499 | Besides numbers, Python can also manipulate strings, enclosed in |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 500 | single quotes or double quotes: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 501 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 502 | \bcode\begin{verbatim} |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 503 | >>> 'spam eggs' |
| 504 | 'spam eggs' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 505 | >>> 'doesn\'t' |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 506 | "doesn't" |
| 507 | >>> "doesn't" |
| 508 | "doesn't" |
| 509 | >>> '"Yes," he said.' |
| 510 | '"Yes," he said.' |
| 511 | >>> "\"Yes,\" he said." |
| 512 | '"Yes," he said.' |
| 513 | >>> '"Isn\'t," she said.' |
| 514 | '"Isn\'t," she said.' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 515 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 516 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 517 | % |
| 518 | Strings are written the same way as they are typed for input: inside |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 519 | quotes and with quotes and other funny characters escaped by backslashes, |
| 520 | to show the precise value. The string is enclosed in double quotes if |
| 521 | the string contains a single quote and no double quotes, else it's |
| 522 | enclosed in single quotes. (The {\tt print} statement, described later, |
| 523 | can be used to write strings without quotes or escapes.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 524 | |
| 525 | Strings can be concatenated (glued together) with the {\tt +} |
| 526 | operator, and repeated with {\tt *}: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 527 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 528 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 529 | >>> word = 'Help' + 'A' |
| 530 | >>> word |
| 531 | 'HelpA' |
| 532 | >>> '<' + word*5 + '>' |
| 533 | '<HelpAHelpAHelpAHelpAHelpA>' |
| 534 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 535 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 536 | % |
| 537 | Strings can be subscripted (indexed); like in C, the first character of |
| 538 | a string has subscript (index) 0. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 539 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 540 | There is no separate character type; a character is simply a string of |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 541 | size one. Like in Icon, substrings can be specified with the {\em |
| 542 | slice} notation: two indices separated by a colon. |
| 543 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 544 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 545 | >>> word[4] |
| 546 | 'A' |
| 547 | >>> word[0:2] |
| 548 | 'He' |
| 549 | >>> word[2:4] |
| 550 | 'lp' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 551 | >>> |
| 552 | \end{verbatim}\ecode |
| 553 | % |
| 554 | Slice indices have useful defaults; an omitted first index defaults to |
| 555 | zero, an omitted second index defaults to the size of the string being |
| 556 | sliced. |
| 557 | |
| 558 | \bcode\begin{verbatim} |
| 559 | >>> word[:2] # The first two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 560 | 'He' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 561 | >>> word[2:] # All but the first two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 562 | 'lpA' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 563 | >>> |
| 564 | \end{verbatim}\ecode |
| 565 | % |
| 566 | Here's a useful invariant of slice operations: \verb\s[:i] + s[i:]\ |
| 567 | equals \verb\s\. |
| 568 | |
| 569 | \bcode\begin{verbatim} |
| 570 | >>> word[:2] + word[2:] |
| 571 | 'HelpA' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 572 | >>> word[:3] + word[3:] |
| 573 | 'HelpA' |
| 574 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 575 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 576 | % |
| 577 | Degenerate slice indices are handled gracefully: an index that is too |
| 578 | large is replaced by the string size, an upper bound smaller than the |
| 579 | lower bound returns an empty string. |
| 580 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 581 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 582 | >>> word[1:100] |
| 583 | 'elpA' |
| 584 | >>> word[10:] |
| 585 | '' |
| 586 | >>> word[2:1] |
| 587 | '' |
| 588 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 589 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 590 | % |
| 591 | Indices may be negative numbers, to start counting from the right. |
| 592 | For example: |
| 593 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 594 | \bcode\begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 595 | >>> word[-1] # The last character |
| 596 | 'A' |
| 597 | >>> word[-2] # The last-but-one character |
| 598 | 'p' |
| 599 | >>> word[-2:] # The last two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 600 | 'pA' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 601 | >>> word[:-2] # All but the last two characters |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 602 | 'Hel' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 603 | >>> |
| 604 | \end{verbatim}\ecode |
| 605 | % |
| 606 | But note that -0 is really the same as 0, so it does not count from |
| 607 | the right! |
| 608 | |
| 609 | \bcode\begin{verbatim} |
| 610 | >>> word[-0] # (since -0 equals 0) |
| 611 | 'H' |
| 612 | >>> |
| 613 | \end{verbatim}\ecode |
| 614 | % |
| 615 | Out-of-range negative slice indices are truncated, but don't try this |
| 616 | for single-element (non-slice) indices: |
| 617 | |
| 618 | \bcode\begin{verbatim} |
| 619 | >>> word[-100:] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 620 | 'HelpA' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 621 | >>> word[-10] # error |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 622 | Traceback (innermost last): |
| 623 | File "<stdin>", line 1 |
| 624 | IndexError: string index out of range |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 625 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 626 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 627 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 628 | The best way to remember how slices work is to think of the indices as |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 629 | pointing {\em between} characters, with the left edge of the first |
| 630 | character numbered 0. Then the right edge of the last character of a |
| 631 | string of {\tt n} characters has index {\tt n}, for example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 632 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 633 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 634 | +---+---+---+---+---+ |
| 635 | | H | e | l | p | A | |
| 636 | +---+---+---+---+---+ |
| 637 | 0 1 2 3 4 5 |
| 638 | -5 -4 -3 -2 -1 |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 639 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 640 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 641 | The first row of numbers gives the position of the indices 0...5 in |
| 642 | the string; the second row gives the corresponding negative indices. |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 643 | The slice from \verb\i\ to \verb\j\ consists of all characters between |
| 644 | the edges labeled \verb\i\ and \verb\j\, respectively. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 645 | |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 646 | For nonnegative indices, the length of a slice is the difference of |
| 647 | the indices, if both are within bounds, e.g., the length of |
| 648 | \verb\word[1:3]\ is 2. |
| 649 | |
| 650 | The built-in function {\tt len()} returns the length of a string: |
| 651 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 652 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 653 | >>> s = 'supercalifragilisticexpialidocious' |
| 654 | >>> len(s) |
| 655 | 34 |
| 656 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 657 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 658 | |
| 659 | \subsection{Lists} |
| 660 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 661 | Python knows a number of {\em compound} data types, used to group |
| 662 | together other values. The most versatile is the {\em list}, which |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 663 | can be written as a list of comma-separated values (items) between |
| 664 | square brackets. List items need not all have the same type. |
| 665 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 666 | \bcode\begin{verbatim} |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 667 | >>> a = ['spam', 'eggs', 100, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 668 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 669 | ['spam', 'eggs', 100, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 670 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 671 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 672 | % |
| 673 | Like string indices, list indices start at 0, and lists can be sliced, |
| 674 | concatenated and so on: |
| 675 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 676 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 677 | >>> a[0] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 678 | 'spam' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 679 | >>> a[3] |
| 680 | 1234 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 681 | >>> a[-2] |
| 682 | 100 |
| 683 | >>> a[1:-1] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 684 | ['eggs', 100] |
| 685 | >>> a[:2] + ['bacon', 2*2] |
| 686 | ['spam', 'eggs', 'bacon', 4] |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 687 | >>> 3*a[:3] + ['Boe!'] |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 688 | ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 689 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 690 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 691 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 692 | Unlike strings, which are {\em immutable}, it is possible to change |
| 693 | individual elements of a list: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 694 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 695 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 696 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 697 | ['spam', 'eggs', 100, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 698 | >>> a[2] = a[2] + 23 |
| 699 | >>> a |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 700 | ['spam', 'eggs', 123, 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 701 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 702 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 703 | % |
| 704 | 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] | 705 | of the list: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 706 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 707 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 708 | >>> # Replace some items: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 709 | ... a[0:2] = [1, 12] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 710 | >>> a |
| 711 | [1, 12, 123, 1234] |
| 712 | >>> # Remove some: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 713 | ... a[0:2] = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 714 | >>> a |
| 715 | [123, 1234] |
| 716 | >>> # Insert some: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 717 | ... a[1:1] = ['bletch', 'xyzzy'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 718 | >>> a |
| 719 | [123, 'bletch', 'xyzzy', 1234] |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 720 | >>> a[:0] = a # Insert (a copy of) itself at the beginning |
| 721 | >>> a |
| 722 | [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 723 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 724 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 725 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 726 | The built-in function {\tt len()} also applies to lists: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 727 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 728 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 729 | >>> len(a) |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 730 | 8 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 731 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 732 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 733 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 734 | It is possible to nest lists (create lists containing other lists), |
| 735 | for example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 736 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 737 | \bcode\begin{verbatim} |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 738 | >>> q = [2, 3] |
| 739 | >>> p = [1, q, 4] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 740 | >>> len(p) |
| 741 | 3 |
| 742 | >>> p[1] |
| 743 | [2, 3] |
| 744 | >>> p[1][0] |
| 745 | 2 |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 746 | >>> p[1].append('xtra') # See section 5.1 |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 747 | >>> p |
| 748 | [1, [2, 3, 'xtra'], 4] |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 749 | >>> q |
| 750 | [2, 3, 'xtra'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 751 | >>> |
| 752 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 753 | % |
| 754 | Note that in the last example, {\tt p[1]} and {\tt q} really refer to |
| 755 | the same object! We'll come back to {\em object semantics} later. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 756 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 757 | \section{First Steps Towards Programming} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 758 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 759 | Of course, we can use Python for more complicated tasks than adding |
| 760 | two and two together. For instance, we can write an initial |
| 761 | subsequence of the {\em Fibonacci} series as follows: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 762 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 763 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 764 | >>> # Fibonacci series: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 765 | ... # the sum of two elements defines the next |
| 766 | ... a, b = 0, 1 |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 767 | >>> while b < 10: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 768 | ... print b |
| 769 | ... a, b = b, a+b |
| 770 | ... |
| 771 | 1 |
| 772 | 1 |
| 773 | 2 |
| 774 | 3 |
| 775 | 5 |
| 776 | 8 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 777 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 778 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 779 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 780 | This example introduces several new features. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 781 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 782 | \begin{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 783 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 784 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 785 | The first line contains a {\em multiple assignment}: the variables |
| 786 | {\tt a} and {\tt b} simultaneously get the new values 0 and 1. On the |
| 787 | last line this is used again, demonstrating that the expressions on |
| 788 | the right-hand side are all evaluated first before any of the |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 789 | assignments take place. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 790 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 791 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 792 | The {\tt while} loop executes as long as the condition (here: {\tt b < |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 793 | 10}) remains true. In Python, like in C, any non-zero integer value is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 794 | true; zero is false. The condition may also be a string or list value, |
| 795 | in fact any sequence; anything with a non-zero length is true, empty |
| 796 | sequences are false. The test used in the example is a simple |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 797 | comparison. The standard comparison operators are written the same as |
| 798 | in C: {\tt <}, {\tt >}, {\tt ==}, {\tt <=}, {\tt >=} and {\tt !=}. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 799 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 800 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 801 | The {\em body} of the loop is {\em indented}: indentation is Python's |
| 802 | way of grouping statements. Python does not (yet!) provide an |
| 803 | intelligent input line editing facility, so you have to type a tab or |
| 804 | space(s) for each indented line. In practice you will prepare more |
| 805 | complicated input for Python with a text editor; most text editors have |
| 806 | an auto-indent facility. When a compound statement is entered |
| 807 | interactively, it must be followed by a blank line to indicate |
| 808 | completion (since the parser cannot guess when you have typed the last |
| 809 | line). |
| 810 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 811 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 812 | The {\tt print} statement writes the value of the expression(s) it is |
| 813 | given. It differs from just writing the expression you want to write |
| 814 | (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] | 815 | multiple expressions and strings. Strings are printed without quotes, |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 816 | and a space is inserted between items, so you can format things nicely, |
| 817 | like this: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 818 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 819 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 820 | >>> i = 256*256 |
| 821 | >>> print 'The value of i is', i |
| 822 | The value of i is 65536 |
| 823 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 824 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 825 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 826 | A trailing comma avoids the newline after the output: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 827 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 828 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 829 | >>> a, b = 0, 1 |
| 830 | >>> while b < 1000: |
| 831 | ... print b, |
| 832 | ... a, b = b, a+b |
| 833 | ... |
| 834 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
| 835 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 836 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 837 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 838 | Note that the interpreter inserts a newline before it prints the next |
| 839 | prompt if the last line was not completed. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 840 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 841 | \end{itemize} |
| 842 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 843 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 844 | \chapter{More Control Flow Tools} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 845 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 846 | Besides the {\tt while} statement just introduced, Python knows the |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 847 | usual control flow statements known from other languages, with some |
| 848 | twists. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 849 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 850 | \section{If Statements} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 851 | |
| 852 | Perhaps the most well-known statement type is the {\tt if} statement. |
| 853 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 854 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 855 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 856 | >>> if x < 0: |
| 857 | ... x = 0 |
| 858 | ... print 'Negative changed to zero' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 859 | ... elif x == 0: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 860 | ... print 'Zero' |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 861 | ... elif x == 1: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 862 | ... print 'Single' |
| 863 | ... else: |
| 864 | ... print 'More' |
| 865 | ... |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 866 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 867 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 868 | There can be zero or more {\tt elif} parts, and the {\tt else} part is |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 869 | optional. The keyword `{\tt elif}' is short for `{\tt else if}', and is |
| 870 | useful to avoid excessive indentation. An {\tt if...elif...elif...} |
| 871 | sequence is a substitute for the {\em switch} or {\em case} statements |
| 872 | found in other languages. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 873 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 874 | \section{For Statements} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 875 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 876 | The {\tt for} statement in Python differs a bit from what you may be |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 877 | used to in C or Pascal. Rather than always iterating over an |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 878 | arithmetic progression of numbers (like in Pascal), or leaving the user |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 879 | completely free in the iteration test and step (as C), Python's {\tt |
| 880 | for} statement iterates over the items of any sequence (e.g., a list |
| 881 | or a string), in the order that they appear in the sequence. For |
| 882 | example (no pun intended): |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 883 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 884 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 885 | >>> # Measure some strings: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 886 | ... a = ['cat', 'window', 'defenestrate'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 887 | >>> for x in a: |
| 888 | ... print x, len(x) |
| 889 | ... |
| 890 | cat 3 |
| 891 | window 6 |
| 892 | defenestrate 12 |
| 893 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 894 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 895 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 896 | It is not safe to modify the sequence being iterated over in the loop |
| 897 | (this can only happen for mutable sequence types, i.e., lists). If |
| 898 | you need to modify the list you are iterating over, e.g., duplicate |
| 899 | selected items, you must iterate over a copy. The slice notation |
| 900 | makes this particularly convenient: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 901 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 902 | \bcode\begin{verbatim} |
| 903 | >>> for x in a[:]: # make a slice copy of the entire list |
| 904 | ... if len(x) > 6: a.insert(0, x) |
| 905 | ... |
| 906 | >>> a |
| 907 | ['defenestrate', 'cat', 'window', 'defenestrate'] |
| 908 | >>> |
| 909 | \end{verbatim}\ecode |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 910 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 911 | \section{The {\tt range()} Function} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 912 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 913 | If you do need to iterate over a sequence of numbers, the built-in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 914 | function {\tt range()} comes in handy. It generates lists containing |
| 915 | arithmetic progressions, e.g.: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 916 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 917 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 918 | >>> range(10) |
| 919 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
| 920 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 921 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 922 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 923 | The given end point is never part of the generated list; {\tt range(10)} |
| 924 | generates a list of 10 values, exactly the legal indices for items of a |
| 925 | sequence of length 10. It is possible to let the range start at another |
| 926 | number, or to specify a different increment (even negative): |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 927 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 928 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 929 | >>> range(5, 10) |
| 930 | [5, 6, 7, 8, 9] |
| 931 | >>> range(0, 10, 3) |
| 932 | [0, 3, 6, 9] |
| 933 | >>> range(-10, -100, -30) |
| 934 | [-10, -40, -70] |
| 935 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 936 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 937 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 938 | To iterate over the indices of a sequence, combine {\tt range()} and |
| 939 | {\tt len()} as follows: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 940 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 941 | \bcode\begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 942 | >>> a = ['Mary', 'had', 'a', 'little', 'lamb'] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 943 | >>> for i in range(len(a)): |
| 944 | ... print i, a[i] |
| 945 | ... |
| 946 | 0 Mary |
| 947 | 1 had |
| 948 | 2 a |
| 949 | 3 little |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 950 | 4 lamb |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 951 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 952 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 953 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 954 | \section{Break and Continue Statements, and Else Clauses on Loops} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 955 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 956 | The {\tt break} statement, like in C, breaks out of the smallest |
| 957 | enclosing {\tt for} or {\tt while} loop. |
| 958 | |
| 959 | The {\tt continue} statement, also borrowed from C, continues with the |
| 960 | next iteration of the loop. |
| 961 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 962 | Loop statements may have an {\tt else} clause; it is executed when the |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 963 | loop terminates through exhaustion of the list (with {\tt for}) or when |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 964 | the condition becomes false (with {\tt while}), but not when the loop is |
| 965 | terminated by a {\tt break} statement. This is exemplified by the |
Guido van Rossum | cfb45e4 | 1994-11-10 23:04:43 +0000 | [diff] [blame] | 966 | following loop, which searches for prime numbers: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 967 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 968 | \bcode\begin{verbatim} |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 969 | >>> for n in range(2, 10): |
| 970 | ... for x in range(2, n): |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 971 | ... if n % x == 0: |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 972 | ... print n, 'equals', x, '*', n/x |
| 973 | ... break |
| 974 | ... else: |
| 975 | ... print n, 'is a prime number' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 976 | ... |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 977 | 2 is a prime number |
| 978 | 3 is a prime number |
| 979 | 4 equals 2 * 2 |
| 980 | 5 is a prime number |
| 981 | 6 equals 2 * 3 |
| 982 | 7 is a prime number |
| 983 | 8 equals 2 * 4 |
| 984 | 9 equals 3 * 3 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 985 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 986 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 987 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 988 | \section{Pass Statements} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 989 | |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 990 | The {\tt pass} statement does nothing. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 991 | It can be used when a statement is required syntactically but the |
| 992 | program requires no action. |
| 993 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 994 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 995 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 996 | >>> while 1: |
| 997 | ... pass # Busy-wait for keyboard interrupt |
| 998 | ... |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 999 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1000 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1001 | \section{Defining Functions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1002 | |
| 1003 | We can create a function that writes the Fibonacci series to an |
| 1004 | arbitrary boundary: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1005 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1006 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1007 | >>> def fib(n): # write Fibonacci series up to n |
| 1008 | ... a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1009 | ... while b < n: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1010 | ... print b, |
| 1011 | ... a, b = b, a+b |
| 1012 | ... |
| 1013 | >>> # Now call the function we just defined: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1014 | ... fib(2000) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1015 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 |
| 1016 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1017 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1018 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1019 | The keyword {\tt def} introduces a function {\em definition}. It must |
| 1020 | be followed by the function name and the parenthesized list of formal |
| 1021 | parameters. The statements that form the body of the function starts at |
| 1022 | the next line, indented by a tab stop. |
| 1023 | |
| 1024 | The {\em execution} of a function introduces a new symbol table used |
| 1025 | for the local variables of the function. More precisely, all variable |
| 1026 | assignments in a function store the value in the local symbol table; |
| 1027 | whereas |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1028 | variable references first look in the local symbol table, then |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1029 | in the global symbol table, and then in the table of built-in names. |
| 1030 | Thus, |
Guido van Rossum | cfb45e4 | 1994-11-10 23:04:43 +0000 | [diff] [blame] | 1031 | global variables cannot be directly assigned a value within a |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1032 | function (unless named in a {\tt global} statement), although |
| 1033 | they may be referenced. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1034 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1035 | The actual parameters (arguments) to a function call are introduced in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1036 | the local symbol table of the called function when it is called; thus, |
| 1037 | arguments are passed using {\em call\ by\ value}.% |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1038 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1039 | Actually, {\em call by object reference} would be a better |
| 1040 | description, since if a mutable object is passed, the caller |
| 1041 | will see any changes the callee makes to it (e.g., items |
| 1042 | inserted into a list). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1043 | } |
| 1044 | When a function calls another function, a new local symbol table is |
| 1045 | created for that call. |
| 1046 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1047 | A function definition introduces the function name in the |
| 1048 | current |
| 1049 | symbol table. The value |
| 1050 | of the function name |
| 1051 | has a type that is recognized by the interpreter as a user-defined |
| 1052 | function. This value can be assigned to another name which can then |
| 1053 | also be used as a function. This serves as a general renaming |
| 1054 | mechanism: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1055 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1056 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1057 | >>> fib |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1058 | <function object at 10042ed0> |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1059 | >>> f = fib |
| 1060 | >>> f(100) |
| 1061 | 1 1 2 3 5 8 13 21 34 55 89 |
| 1062 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1063 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1064 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1065 | You might object that {\tt fib} is not a function but a procedure. In |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1066 | 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] | 1067 | value. In fact, technically speaking, procedures do return a value, |
| 1068 | albeit a rather boring one. This value is called {\tt None} (it's a |
| 1069 | built-in name). Writing the value {\tt None} is normally suppressed by |
| 1070 | the interpreter if it would be the only value written. You can see it |
| 1071 | if you really want to: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1072 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1073 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1074 | >>> print fib(0) |
| 1075 | None |
| 1076 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1077 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1078 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1079 | It is simple to write a function that returns a list of the numbers of |
| 1080 | the Fibonacci series, instead of printing it: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1081 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1082 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1083 | >>> def fib2(n): # return Fibonacci series up to n |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1084 | ... result = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1085 | ... a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1086 | ... while b < n: |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1087 | ... result.append(b) # see below |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1088 | ... a, b = b, a+b |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1089 | ... return result |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1090 | ... |
| 1091 | >>> f100 = fib2(100) # call it |
| 1092 | >>> f100 # write the result |
| 1093 | [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
| 1094 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1095 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1096 | % |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1097 | This example, as usual, demonstrates some new Python features: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1098 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1099 | \begin{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1100 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1101 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1102 | The {\tt return} statement returns with a value from a function. {\tt |
| 1103 | return} without an expression argument is used to return from the middle |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1104 | of a procedure (falling off the end also returns from a procedure), in |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1105 | which case the {\tt None} value is returned. |
| 1106 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1107 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1108 | The statement {\tt result.append(b)} calls a {\em method} of the list |
| 1109 | object {\tt result}. A method is a function that `belongs' to an |
| 1110 | object and is named {\tt obj.methodname}, where {\tt obj} is some |
| 1111 | object (this may be an expression), and {\tt methodname} is the name |
| 1112 | of a method that is defined by the object's type. Different types |
| 1113 | define different methods. Methods of different types may have the |
| 1114 | same name without causing ambiguity. (It is possible to define your |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1115 | own object types and methods, using {\em classes}, as discussed later |
| 1116 | in this tutorial.) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1117 | The method {\tt append} shown in the example, is defined for |
| 1118 | list objects; it adds a new element at the end of the list. In this |
| 1119 | example |
| 1120 | it is equivalent to {\tt result = result + [b]}, but more efficient. |
| 1121 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1122 | \end{itemize} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1123 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1124 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1125 | \chapter{Odds and Ends} |
| 1126 | |
| 1127 | This chapter describes some things you've learned about already in |
| 1128 | more detail, and adds some new things as well. |
| 1129 | |
| 1130 | \section{More on Lists} |
| 1131 | |
| 1132 | The list data type has some more methods. Here are all of the methods |
| 1133 | of lists objects: |
| 1134 | |
Guido van Rossum | 7d9f8d7 | 1991-01-22 11:45:00 +0000 | [diff] [blame] | 1135 | \begin{description} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1136 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1137 | \item[{\tt insert(i, x)}] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1138 | Insert an item at a given position. The first argument is the index of |
| 1139 | the element before which to insert, so {\tt a.insert(0, x)} inserts at |
| 1140 | the front of the list, and {\tt a.insert(len(a), x)} is equivalent to |
| 1141 | {\tt a.append(x)}. |
| 1142 | |
| 1143 | \item[{\tt append(x)}] |
| 1144 | Equivalent to {\tt a.insert(len(a), x)}. |
| 1145 | |
| 1146 | \item[{\tt index(x)}] |
| 1147 | Return the index in the list of the first item whose value is {\tt x}. |
| 1148 | It is an error if there is no such item. |
| 1149 | |
| 1150 | \item[{\tt remove(x)}] |
| 1151 | Remove the first item from the list whose value is {\tt x}. |
| 1152 | It is an error if there is no such item. |
| 1153 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1154 | \item[{\tt sort()}] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1155 | Sort the items of the list, in place. |
| 1156 | |
| 1157 | \item[{\tt reverse()}] |
| 1158 | Reverse the elements of the list, in place. |
| 1159 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1160 | \item[{\tt count(x)}] |
| 1161 | Return the number of times {\tt x} appears in the list. |
| 1162 | |
Guido van Rossum | 7d9f8d7 | 1991-01-22 11:45:00 +0000 | [diff] [blame] | 1163 | \end{description} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1164 | |
| 1165 | An example that uses all list methods: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1166 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1167 | \bcode\begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1168 | >>> a = [66.6, 333, 333, 1, 1234.5] |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1169 | >>> print a.count(333), a.count(66.6), a.count('x') |
| 1170 | 2 1 0 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1171 | >>> a.insert(2, -1) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1172 | >>> a.append(333) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1173 | >>> a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1174 | [66.6, 333, -1, 333, 1, 1234.5, 333] |
| 1175 | >>> a.index(333) |
| 1176 | 1 |
| 1177 | >>> a.remove(333) |
| 1178 | >>> a |
| 1179 | [66.6, -1, 333, 1, 1234.5, 333] |
| 1180 | >>> a.reverse() |
| 1181 | >>> a |
| 1182 | [333, 1234.5, 1, 333, -1, 66.6] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1183 | >>> a.sort() |
| 1184 | >>> a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1185 | [-1, 1, 66.6, 333, 333, 1234.5] |
| 1186 | >>> |
| 1187 | \end{verbatim}\ecode |
| 1188 | |
| 1189 | \section{The {\tt del} statement} |
| 1190 | |
| 1191 | There is a way to remove an item from a list given its index instead |
| 1192 | of its value: the {\tt del} statement. This can also be used to |
| 1193 | remove slices from a list (which we did earlier by assignment of an |
| 1194 | empty list to the slice). For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1195 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1196 | \bcode\begin{verbatim} |
| 1197 | >>> a |
| 1198 | [-1, 1, 66.6, 333, 333, 1234.5] |
| 1199 | >>> del a[0] |
| 1200 | >>> a |
| 1201 | [1, 66.6, 333, 333, 1234.5] |
| 1202 | >>> del a[2:4] |
| 1203 | >>> a |
| 1204 | [1, 66.6, 1234.5] |
| 1205 | >>> |
| 1206 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1207 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1208 | {\tt del} can also be used to delete entire variables: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1209 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1210 | \bcode\begin{verbatim} |
| 1211 | >>> del a |
| 1212 | >>> |
| 1213 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1214 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1215 | Referencing the name {\tt a} hereafter is an error (at least until |
| 1216 | another value is assigned to it). We'll find other uses for {\tt del} |
| 1217 | later. |
| 1218 | |
| 1219 | \section{Tuples and Sequences} |
| 1220 | |
| 1221 | We saw that lists and strings have many common properties, e.g., |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1222 | indexing and slicing operations. They are two examples of {\em |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1223 | sequence} data types. Since Python is an evolving language, other |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1224 | sequence data types may be added. There is also another standard |
| 1225 | sequence data type: the {\em tuple}. |
| 1226 | |
| 1227 | A tuple consists of a number of values separated by commas, for |
| 1228 | instance: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1229 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1230 | \bcode\begin{verbatim} |
| 1231 | >>> t = 12345, 54321, 'hello!' |
| 1232 | >>> t[0] |
| 1233 | 12345 |
| 1234 | >>> t |
| 1235 | (12345, 54321, 'hello!') |
| 1236 | >>> # Tuples may be nested: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1237 | ... u = t, (1, 2, 3, 4, 5) |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1238 | >>> u |
| 1239 | ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5)) |
| 1240 | >>> |
| 1241 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1242 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1243 | As you see, on output tuples are alway enclosed in parentheses, so |
| 1244 | that nested tuples are interpreted correctly; they may be input with |
| 1245 | or without surrounding parentheses, although often parentheses are |
| 1246 | necessary anyway (if the tuple is part of a larger expression). |
| 1247 | |
| 1248 | Tuples have many uses, e.g., (x, y) coordinate pairs, employee records |
| 1249 | from a database, etc. Tuples, like strings, are immutable: it is not |
| 1250 | possible to assign to the individual items of a tuple (you can |
| 1251 | simulate much of the same effect with slicing and concatenation, |
| 1252 | though). |
| 1253 | |
| 1254 | 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] | 1255 | items: the syntax has some extra quirks to accommodate these. Empty |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1256 | tuples are constructed by an empty pair of parentheses; a tuple with |
| 1257 | one item is constructed by following a value with a comma |
| 1258 | (it is not sufficient to enclose a single value in parentheses). |
| 1259 | Ugly, but effective. For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1260 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1261 | \bcode\begin{verbatim} |
| 1262 | >>> empty = () |
| 1263 | >>> singleton = 'hello', # <-- note trailing comma |
| 1264 | >>> len(empty) |
| 1265 | 0 |
| 1266 | >>> len(singleton) |
| 1267 | 1 |
| 1268 | >>> singleton |
| 1269 | ('hello',) |
| 1270 | >>> |
| 1271 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1272 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1273 | The statement {\tt t = 12345, 54321, 'hello!'} is an example of {\em |
| 1274 | tuple packing}: the values {\tt 12345}, {\tt 54321} and {\tt 'hello!'} |
| 1275 | are packed together in a tuple. The reverse operation is also |
| 1276 | possible, e.g.: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1277 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1278 | \bcode\begin{verbatim} |
| 1279 | >>> x, y, z = t |
| 1280 | >>> |
| 1281 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1282 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1283 | This is called, appropriately enough, {\em tuple unpacking}. Tuple |
| 1284 | unpacking requires that the list of variables on the left has the same |
| 1285 | number of elements as the length of the tuple. Note that multiple |
| 1286 | assignment is really just a combination of tuple packing and tuple |
| 1287 | unpacking! |
| 1288 | |
| 1289 | Occasionally, the corresponding operation on lists is useful: {\em list |
| 1290 | unpacking}. This is supported by enclosing the list of variables in |
| 1291 | square brackets: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1292 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1293 | \bcode\begin{verbatim} |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1294 | >>> a = ['spam', 'eggs', 100, 1234] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1295 | >>> [a1, a2, a3, a4] = a |
| 1296 | >>> |
| 1297 | \end{verbatim}\ecode |
| 1298 | |
| 1299 | \section{Dictionaries} |
| 1300 | |
| 1301 | Another useful data type built into Python is the {\em dictionary}. |
| 1302 | Dictionaries are sometimes found in other languages as ``associative |
| 1303 | memories'' or ``associative arrays''. Unlike sequences, which are |
| 1304 | indexed by a range of numbers, dictionaries are indexed by {\em keys}, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1305 | which are strings (the use of non-string values as keys |
| 1306 | is supported, but beyond the scope of this tutorial). |
| 1307 | It is best to think of a dictionary as an unordered set of |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1308 | {\em key:value} pairs, with the requirement that the keys are unique |
| 1309 | (within one dictionary). |
| 1310 | A pair of braces creates an empty dictionary: \verb/{}/. |
| 1311 | Placing a comma-separated list of key:value pairs within the |
| 1312 | braces adds initial key:value pairs to the dictionary; this is also the |
| 1313 | way dictionaries are written on output. |
| 1314 | |
| 1315 | The main operations on a dictionary are storing a value with some key |
| 1316 | and extracting the value given the key. It is also possible to delete |
| 1317 | a key:value pair |
| 1318 | with {\tt del}. |
| 1319 | If you store using a key that is already in use, the old value |
| 1320 | 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] | 1321 | value using a non-existent key. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1322 | |
| 1323 | The {\tt keys()} method of a dictionary object returns a list of all the |
| 1324 | keys used in the dictionary, in random order (if you want it sorted, |
| 1325 | just apply the {\tt sort()} method to the list of keys). To check |
| 1326 | whether a single key is in the dictionary, use the \verb/has_key()/ |
| 1327 | method of the dictionary. |
| 1328 | |
| 1329 | Here is a small example using a dictionary: |
| 1330 | |
| 1331 | \bcode\begin{verbatim} |
| 1332 | >>> tel = {'jack': 4098, 'sape': 4139} |
| 1333 | >>> tel['guido'] = 4127 |
| 1334 | >>> tel |
Guido van Rossum | 8f96f77 | 1991-11-12 15:45:03 +0000 | [diff] [blame] | 1335 | {'sape': 4139, 'guido': 4127, 'jack': 4098} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1336 | >>> tel['jack'] |
| 1337 | 4098 |
| 1338 | >>> del tel['sape'] |
| 1339 | >>> tel['irv'] = 4127 |
| 1340 | >>> tel |
Guido van Rossum | 8f96f77 | 1991-11-12 15:45:03 +0000 | [diff] [blame] | 1341 | {'guido': 4127, 'irv': 4127, 'jack': 4098} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1342 | >>> tel.keys() |
| 1343 | ['guido', 'irv', 'jack'] |
| 1344 | >>> tel.has_key('guido') |
| 1345 | 1 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1346 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1347 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1348 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1349 | \section{More on Conditions} |
| 1350 | |
| 1351 | The conditions used in {\tt while} and {\tt if} statements above can |
| 1352 | contain other operators besides comparisons. |
| 1353 | |
| 1354 | The comparison operators {\tt in} and {\tt not in} check whether a value |
| 1355 | occurs (does not occur) in a sequence. The operators {\tt is} and {\tt |
| 1356 | is not} compare whether two objects are really the same object; this |
| 1357 | only matters for mutable objects like lists. All comparison operators |
| 1358 | have the same priority, which is lower than that of all numerical |
| 1359 | operators. |
| 1360 | |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1361 | Comparisons can be chained: e.g., {\tt a < b == c} tests whether {\tt a} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1362 | is less than {\tt b} and moreover {\tt b} equals {\tt c}. |
| 1363 | |
| 1364 | Comparisons may be combined by the Boolean operators {\tt and} and {\tt |
| 1365 | or}, and the outcome of a comparison (or of any other Boolean |
| 1366 | expression) may be negated with {\tt not}. These all have lower |
| 1367 | priorities than comparison operators again; between them, {\tt not} has |
| 1368 | the highest priority, and {\tt or} the lowest, so that |
| 1369 | {\tt A and not B or C} is equivalent to {\tt (A and (not B)) or C}. Of |
| 1370 | course, parentheses can be used to express the desired composition. |
| 1371 | |
| 1372 | The Boolean operators {\tt and} and {\tt or} are so-called {\em |
| 1373 | shortcut} operators: their arguments are evaluated from left to right, |
| 1374 | and evaluation stops as soon as the outcome is determined. E.g., if |
| 1375 | {\tt A} and {\tt C} are true but {\tt B} is false, {\tt A and B and C} |
| 1376 | does not evaluate the expression C. In general, the return value of a |
| 1377 | shortcut operator, when used as a general value and not as a Boolean, is |
| 1378 | the last evaluated argument. |
| 1379 | |
| 1380 | 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] | 1381 | expression to a variable. For example, |
| 1382 | |
| 1383 | \bcode\begin{verbatim} |
| 1384 | >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance' |
| 1385 | >>> non_null = string1 or string2 or string3 |
| 1386 | >>> non_null |
| 1387 | 'Trondheim' |
| 1388 | >>> |
| 1389 | \end{verbatim}\ecode |
| 1390 | % |
| 1391 | Note that in Python, unlike C, assignment cannot occur inside expressions. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1392 | |
| 1393 | \section{Comparing Sequences and Other Types} |
| 1394 | |
| 1395 | Sequence objects may be compared to other objects with the same |
| 1396 | sequence type. The comparison uses {\em lexicographical} ordering: |
| 1397 | first the first two items are compared, and if they differ this |
| 1398 | determines the outcome of the comparison; if they are equal, the next |
| 1399 | two items are compared, and so on, until either sequence is exhausted. |
| 1400 | 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] | 1401 | the lexicographical comparison is carried out recursively. If all |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1402 | items of two sequences compare equal, the sequences are considered |
| 1403 | equal. If one sequence is an initial subsequence of the other, the |
| 1404 | shorted sequence is the smaller one. Lexicographical ordering for |
Guido van Rossum | 47b4c0f | 1995-03-15 11:25:32 +0000 | [diff] [blame] | 1405 | strings uses the \ASCII{} ordering for individual characters. Some |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1406 | examples of comparisons between sequences with the same types: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1407 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1408 | \bcode\begin{verbatim} |
| 1409 | (1, 2, 3) < (1, 2, 4) |
| 1410 | [1, 2, 3] < [1, 2, 4] |
| 1411 | 'ABC' < 'C' < 'Pascal' < 'Python' |
| 1412 | (1, 2, 3, 4) < (1, 2, 4) |
| 1413 | (1, 2) < (1, 2, -1) |
| 1414 | (1, 2, 3) = (1.0, 2.0, 3.0) |
| 1415 | (1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4) |
| 1416 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1417 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1418 | Note that comparing objects of different types is legal. The outcome |
| 1419 | is deterministic but arbitrary: the types are ordered by their name. |
| 1420 | Thus, a list is always smaller than a string, a string is always |
| 1421 | smaller than a tuple, etc. Mixed numeric types are compared according |
| 1422 | to their numeric value, so 0 equals 0.0, etc.% |
| 1423 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1424 | The rules for comparing objects of different types should |
| 1425 | not be relied upon; they may change in a future version of |
| 1426 | the language. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1427 | } |
| 1428 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1429 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1430 | \chapter{Modules} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1431 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1432 | 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] | 1433 | definitions you have made (functions and variables) are lost. |
| 1434 | Therefore, if you want to write a somewhat longer program, you are |
| 1435 | 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] | 1436 | and running it with that file as input instead. This is known as creating a |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1437 | {\em script}. As your program gets longer, you may want to split it |
| 1438 | into several files for easier maintenance. You may also want to use a |
| 1439 | handy function that you've written in several programs without copying |
| 1440 | its definition into each program. |
| 1441 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1442 | 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] | 1443 | them in a script or in an interactive instance of the interpreter. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1444 | Such a file is called a {\em module}; definitions from a module can be |
| 1445 | {\em imported} into other modules or into the {\em main} module (the |
| 1446 | collection of variables that you have access to in a script |
| 1447 | executed at the top level |
| 1448 | and in calculator mode). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1449 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1450 | A module is a file containing Python definitions and statements. The |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1451 | file name is the module name with the suffix {\tt .py} appended. Within |
| 1452 | a module, the module's name (as a string) is available as the value of |
| 1453 | the global variable {\tt __name__}. For instance, use your favorite text |
| 1454 | editor to create a file called {\tt fibo.py} in the current directory |
| 1455 | with the following contents: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1456 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1457 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1458 | # Fibonacci numbers module |
| 1459 | |
| 1460 | def fib(n): # write Fibonacci series up to n |
| 1461 | a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1462 | while b < n: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1463 | print b, |
| 1464 | a, b = b, a+b |
| 1465 | |
| 1466 | def fib2(n): # return Fibonacci series up to n |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1467 | result = [] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1468 | a, b = 0, 1 |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 1469 | while b < n: |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1470 | result.append(b) |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1471 | a, b = b, a+b |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1472 | return result |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1473 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1474 | % |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1475 | Now enter the Python interpreter and import this module with the |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1476 | following command: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1477 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1478 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1479 | >>> import fibo |
| 1480 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1481 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1482 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1483 | This does not enter the names of the functions defined in |
| 1484 | {\tt fibo} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1485 | directly in the current symbol table; it only enters the module name |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1486 | {\tt fibo} |
| 1487 | there. |
| 1488 | Using the module name you can access the functions: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1489 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1490 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1491 | >>> fibo.fib(1000) |
| 1492 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
| 1493 | >>> fibo.fib2(100) |
| 1494 | [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1495 | >>> fibo.__name__ |
| 1496 | 'fibo' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1497 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1498 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1499 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1500 | 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] | 1501 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1502 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1503 | >>> fib = fibo.fib |
| 1504 | >>> fib(500) |
| 1505 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| 1506 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1507 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1508 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1509 | \section{More on Modules} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1510 | |
| 1511 | A module can contain executable statements as well as function |
| 1512 | definitions. |
| 1513 | These statements are intended to initialize the module. |
| 1514 | They are executed only the |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1515 | {\em first} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1516 | time the module is imported somewhere.% |
| 1517 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1518 | In fact function definitions are also `statements' that are |
| 1519 | `executed'; the execution enters the function name in the |
| 1520 | module's global symbol table. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1521 | } |
| 1522 | |
| 1523 | Each module has its own private symbol table, which is used as the |
| 1524 | global symbol table by all functions defined in the module. |
| 1525 | Thus, the author of a module can use global variables in the module |
| 1526 | without worrying about accidental clashes with a user's global |
| 1527 | variables. |
| 1528 | On the other hand, if you know what you are doing you can touch a |
| 1529 | module's global variables with the same notation used to refer to its |
| 1530 | functions, |
| 1531 | {\tt modname.itemname}. |
| 1532 | |
| 1533 | Modules can import other modules. |
| 1534 | It is customary but not required to place all |
| 1535 | {\tt import} |
| 1536 | statements at the beginning of a module (or script, for that matter). |
| 1537 | The imported module names are placed in the importing module's global |
| 1538 | symbol table. |
| 1539 | |
| 1540 | There is a variant of the |
| 1541 | {\tt import} |
| 1542 | statement that imports names from a module directly into the importing |
| 1543 | module's symbol table. |
| 1544 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1545 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1546 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1547 | >>> from fibo import fib, fib2 |
| 1548 | >>> fib(500) |
| 1549 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| 1550 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1551 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1552 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1553 | This does not introduce the module name from which the imports are taken |
| 1554 | in the local symbol table (so in the example, {\tt fibo} is not |
| 1555 | defined). |
| 1556 | |
| 1557 | 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] | 1558 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1559 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1560 | >>> from fibo import * |
| 1561 | >>> fib(500) |
| 1562 | 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| 1563 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1564 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1565 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1566 | This imports all names except those beginning with an underscore |
Guido van Rossum | 573805a | 1992-03-06 10:56:03 +0000 | [diff] [blame] | 1567 | ({\tt _}). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1568 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1569 | \section{Standard Modules} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1570 | |
Guido van Rossum | 4410c75 | 1991-06-04 20:22:18 +0000 | [diff] [blame] | 1571 | Python comes with a library of standard modules, described in a separate |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1572 | document (Python Library Reference). Some modules are built into the |
| 1573 | interpreter; these provide access to operations that are not part of the |
| 1574 | core of the language but are nevertheless built in, either for |
| 1575 | efficiency or to provide access to operating system primitives such as |
| 1576 | system calls. The set of such modules is a configuration option; e.g., |
| 1577 | the {\tt amoeba} module is only provided on systems that somehow support |
| 1578 | Amoeba primitives. One particular module deserves some attention: {\tt |
| 1579 | sys}, which is built into every Python interpreter. The variables {\tt |
| 1580 | sys.ps1} and {\tt sys.ps2} define the strings used as primary and |
| 1581 | secondary prompts: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1582 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1583 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1584 | >>> import sys |
| 1585 | >>> sys.ps1 |
| 1586 | '>>> ' |
| 1587 | >>> sys.ps2 |
| 1588 | '... ' |
| 1589 | >>> sys.ps1 = 'C> ' |
| 1590 | C> print 'Yuck!' |
| 1591 | Yuck! |
| 1592 | C> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1593 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1594 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1595 | These two variables are only defined if the interpreter is in |
| 1596 | interactive mode. |
| 1597 | |
| 1598 | The variable |
| 1599 | {\tt sys.path} |
| 1600 | is a list of strings that determine the interpreter's search path for |
| 1601 | modules. |
| 1602 | It is initialized to a default path taken from the environment variable |
| 1603 | {\tt PYTHONPATH}, |
| 1604 | or from a built-in default if |
| 1605 | {\tt PYTHONPATH} |
| 1606 | is not set. |
| 1607 | You can modify it using standard list operations, e.g.: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1608 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1609 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1610 | >>> import sys |
| 1611 | >>> sys.path.append('/ufs/guido/lib/python') |
| 1612 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1613 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1614 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1615 | \section{The {\tt dir()} function} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1616 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1617 | The built-in function {\tt dir} is used to find out which names a module |
| 1618 | defines. It returns a sorted list of strings: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1619 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1620 | \bcode\begin{verbatim} |
| 1621 | >>> import fibo, sys |
| 1622 | >>> dir(fibo) |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1623 | ['__name__', 'fib', 'fib2'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1624 | >>> dir(sys) |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1625 | ['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit', |
| 1626 | 'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace', |
| 1627 | 'stderr', 'stdin', 'stdout', 'version'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1628 | >>> |
| 1629 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1630 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1631 | Without arguments, {\tt dir()} lists the names you have defined currently: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1632 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1633 | \bcode\begin{verbatim} |
| 1634 | >>> a = [1, 2, 3, 4, 5] |
| 1635 | >>> import fibo, sys |
| 1636 | >>> fib = fibo.fib |
| 1637 | >>> dir() |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1638 | ['__name__', 'a', 'fib', 'fibo', 'sys'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1639 | >>> |
| 1640 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1641 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1642 | 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] | 1643 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1644 | {\tt dir()} does not list the names of built-in functions and variables. |
| 1645 | If you want a list of those, they are defined in the standard module |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 1646 | {\tt __builtin__}: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1647 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1648 | \bcode\begin{verbatim} |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 1649 | >>> import __builtin__ |
| 1650 | >>> dir(__builtin__) |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1651 | ['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError', |
| 1652 | 'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt', |
| 1653 | 'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError', |
| 1654 | 'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError', |
| 1655 | 'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce', |
| 1656 | 'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float', |
| 1657 | 'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long', |
| 1658 | 'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input', |
| 1659 | 'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange'] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1660 | >>> |
| 1661 | \end{verbatim}\ecode |
| 1662 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1663 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1664 | \chapter{Output Formatting} |
| 1665 | |
| 1666 | So far we've encountered two ways of writing values: {\em expression |
| 1667 | statements} and the {\tt print} statement. (A third way is using the |
| 1668 | {\tt write} method of file objects; the standard output file can be |
| 1669 | referenced as {\tt sys.stdout}. See the Library Reference for more |
| 1670 | information on this.) |
| 1671 | |
| 1672 | Often you'll want more control over the formatting of your output than |
| 1673 | simply printing space-separated values. The key to nice formatting in |
| 1674 | Python is to do all the string handling yourself; using string slicing |
| 1675 | and concatenation operations you can create any lay-out you can imagine. |
| 1676 | The standard module {\tt string} contains some useful operations for |
| 1677 | padding strings to a given column width; these will be discussed shortly. |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1678 | Finally, the \code{\%} operator (modulo) with a string left argument |
| 1679 | interprets this string as a C sprintf format string to be applied to the |
| 1680 | right argument, and returns the string resulting from this formatting |
| 1681 | operation. |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1682 | |
| 1683 | One question remains, of course: how do you convert values to strings? |
| 1684 | Luckily, Python has a way to convert any value to a string: just write |
| 1685 | the value between reverse quotes (\verb/``/). Some examples: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1686 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1687 | \bcode\begin{verbatim} |
| 1688 | >>> x = 10 * 3.14 |
| 1689 | >>> y = 200*200 |
| 1690 | >>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...' |
| 1691 | >>> print s |
| 1692 | The value of x is 31.4, and y is 40000... |
| 1693 | >>> # Reverse quotes work on other types besides numbers: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1694 | ... p = [x, y] |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1695 | >>> ps = `p` |
| 1696 | >>> ps |
| 1697 | '[31.4, 40000]' |
| 1698 | >>> # Converting a string adds string quotes and backslashes: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1699 | ... hello = 'hello, world\n' |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1700 | >>> hellos = `hello` |
| 1701 | >>> print hellos |
| 1702 | 'hello, world\012' |
| 1703 | >>> # The argument of reverse quotes may be a tuple: |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1704 | ... `x, y, ('spam', 'eggs')` |
| 1705 | "(31.4, 40000, ('spam', 'eggs'))" |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1706 | >>> |
| 1707 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1708 | % |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1709 | 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] | 1710 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1711 | \bcode\begin{verbatim} |
| 1712 | >>> import string |
| 1713 | >>> for x in range(1, 11): |
| 1714 | ... print string.rjust(`x`, 2), string.rjust(`x*x`, 3), |
| 1715 | ... # Note trailing comma on previous line |
| 1716 | ... print string.rjust(`x*x*x`, 4) |
| 1717 | ... |
| 1718 | 1 1 1 |
| 1719 | 2 4 8 |
| 1720 | 3 9 27 |
| 1721 | 4 16 64 |
| 1722 | 5 25 125 |
| 1723 | 6 36 216 |
| 1724 | 7 49 343 |
| 1725 | 8 64 512 |
| 1726 | 9 81 729 |
| 1727 | 10 100 1000 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1728 | >>> for x in range(1,11): |
| 1729 | ... print '%2d %3d %4d' % (x, x*x, x*x*x) |
| 1730 | ... |
| 1731 | 1 1 1 |
| 1732 | 2 4 8 |
| 1733 | 3 9 27 |
| 1734 | 4 16 64 |
| 1735 | 5 25 125 |
| 1736 | 6 36 216 |
| 1737 | 7 49 343 |
| 1738 | 8 64 512 |
| 1739 | 9 81 729 |
| 1740 | 10 100 1000 |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1741 | >>> |
| 1742 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1743 | % |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1744 | (Note that one space between each column was added by the way {\tt print} |
| 1745 | works: it always adds spaces between its arguments.) |
| 1746 | |
| 1747 | This example demonstrates the function {\tt string.rjust()}, which |
| 1748 | right-justifies a string in a field of a given width by padding it with |
| 1749 | spaces on the left. There are similar functions {\tt string.ljust()} |
| 1750 | and {\tt string.center()}. These functions do not write anything, they |
| 1751 | just return a new string. If the input string is too long, they don't |
| 1752 | truncate it, but return it unchanged; this will mess up your column |
| 1753 | lay-out but that's usually better than the alternative, which would be |
| 1754 | lying about a value. (If you really want truncation you can always add |
| 1755 | a slice operation, as in {\tt string.ljust(x,~n)[0:n]}.) |
| 1756 | |
| 1757 | There is another function, {\tt string.zfill}, which pads a numeric |
| 1758 | string on the left with zeros. It understands about plus and minus |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1759 | signs: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1760 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1761 | \bcode\begin{verbatim} |
| 1762 | >>> string.zfill('12', 5) |
| 1763 | '00012' |
| 1764 | >>> string.zfill('-3.14', 7) |
| 1765 | '-003.14' |
| 1766 | >>> string.zfill('3.14159265359', 5) |
| 1767 | '3.14159265359' |
| 1768 | >>> |
| 1769 | \end{verbatim}\ecode |
| 1770 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 1771 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1772 | \chapter{Errors and Exceptions} |
| 1773 | |
| 1774 | Until now error messages haven't been more than mentioned, but if you |
| 1775 | have tried out the examples you have probably seen some. There are |
| 1776 | (at least) two distinguishable kinds of errors: {\em syntax\ errors} |
| 1777 | and {\em exceptions}. |
| 1778 | |
| 1779 | \section{Syntax Errors} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1780 | |
| 1781 | 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] | 1782 | kind of complaint you get while you are still learning Python: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1783 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1784 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1785 | >>> while 1 print 'Hello world' |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1786 | File "<stdin>", line 1 |
| 1787 | while 1 print 'Hello world' |
| 1788 | ^ |
| 1789 | SyntaxError: invalid syntax |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1790 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1791 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1792 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1793 | The parser repeats the offending line and displays a little `arrow' |
| 1794 | pointing at the earliest point in the line where the error was detected. |
| 1795 | The error is caused by (or at least detected at) the token |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1796 | {\em preceding} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1797 | the arrow: in the example, the error is detected at the keyword |
| 1798 | {\tt print}, since a colon ({\tt :}) is missing before it. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1799 | File name and line number are printed so you know where to look in case |
| 1800 | the input came from a script. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1801 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1802 | \section{Exceptions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1803 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1804 | Even if a statement or expression is syntactically correct, it may |
| 1805 | cause an error when an attempt is made to execute it. |
| 1806 | Errors detected during execution are called {\em exceptions} and are |
| 1807 | not unconditionally fatal: you will soon learn how to handle them in |
| 1808 | Python programs. Most exceptions are not handled by programs, |
| 1809 | however, and result in error messages as shown here: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1810 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1811 | \bcode\small\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1812 | >>> 10 * (1/0) |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 1813 | Traceback (innermost last): |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1814 | File "<stdin>", line 1 |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1815 | ZeroDivisionError: integer division or modulo |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1816 | >>> 4 + spam*3 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1817 | Traceback (innermost last): |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1818 | File "<stdin>", line 1 |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1819 | NameError: spam |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1820 | >>> '2' + 2 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1821 | Traceback (innermost last): |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1822 | File "<stdin>", line 1 |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1823 | TypeError: illegal argument type for built-in operation |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1824 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1825 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1826 | % |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1827 | The last line of the error message indicates what happened. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1828 | Exceptions come in different types, and the type is printed as part of |
| 1829 | the message: the types in the example are |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1830 | {\tt ZeroDivisionError}, |
| 1831 | {\tt NameError} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1832 | and |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1833 | {\tt TypeError}. |
| 1834 | The string printed as the exception type is the name of the built-in |
| 1835 | name for the exception that occurred. This is true for all built-in |
| 1836 | exceptions, but need not be true for user-defined exceptions (although |
| 1837 | it is a useful convention). |
| 1838 | Standard exception names are built-in identifiers (not reserved |
| 1839 | keywords). |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1840 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1841 | The rest of the line is a detail whose interpretation depends on the |
| 1842 | exception type; its meaning is dependent on the exception type. |
| 1843 | |
| 1844 | The preceding part of the error message shows the context where the |
| 1845 | exception happened, in the form of a stack backtrace. |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1846 | In general it contains a stack backtrace listing source lines; however, |
| 1847 | it will not display lines read from standard input. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1848 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1849 | The Python library reference manual lists the built-in exceptions and |
| 1850 | their meanings. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1851 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1852 | \section{Handling Exceptions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1853 | |
| 1854 | It is possible to write programs that handle selected exceptions. |
| 1855 | Look at the following example, which prints a table of inverses of |
| 1856 | some floating point numbers: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1857 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1858 | \bcode\begin{verbatim} |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1859 | >>> numbers = [0.3333, 2.5, 0, 10] |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1860 | >>> for x in numbers: |
| 1861 | ... print x, |
| 1862 | ... try: |
| 1863 | ... print 1.0 / x |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1864 | ... except ZeroDivisionError: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1865 | ... print '*** has no inverse ***' |
| 1866 | ... |
| 1867 | 0.3333 3.00030003 |
| 1868 | 2.5 0.4 |
| 1869 | 0 *** has no inverse *** |
| 1870 | 10 0.1 |
| 1871 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1872 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1873 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1874 | The {\tt try} statement works as follows. |
| 1875 | \begin{itemize} |
| 1876 | \item |
| 1877 | First, the |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1878 | {\em try\ clause} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1879 | (the statement(s) between the {\tt try} and {\tt except} keywords) is |
| 1880 | executed. |
| 1881 | \item |
| 1882 | If no exception occurs, the |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1883 | {\em except\ clause} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1884 | is skipped and execution of the {\tt try} statement is finished. |
| 1885 | \item |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1886 | If an exception occurs during execution of the try clause, |
| 1887 | the rest of the clause is skipped. Then if |
| 1888 | its type matches the exception named after the {\tt except} keyword, |
| 1889 | the rest of the try clause is skipped, the except clause is executed, |
| 1890 | and then execution continues after the {\tt try} statement. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1891 | \item |
| 1892 | If an exception occurs which does not match the exception named in the |
| 1893 | except clause, it is passed on to outer try statements; if no handler is |
| 1894 | found, it is an |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1895 | {\em unhandled\ exception} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1896 | and execution stops with a message as shown above. |
| 1897 | \end{itemize} |
| 1898 | A {\tt try} statement may have more than one except clause, to specify |
| 1899 | handlers for different exceptions. |
| 1900 | At most one handler will be executed. |
| 1901 | Handlers only handle exceptions that occur in the corresponding try |
| 1902 | clause, not in other handlers of the same {\tt try} statement. |
| 1903 | An except clause may name multiple exceptions as a parenthesized list, |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1904 | e.g.: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1905 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1906 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1907 | ... except (RuntimeError, TypeError, NameError): |
| 1908 | ... pass |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1909 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1910 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1911 | The last except clause may omit the exception name(s), to serve as a |
| 1912 | wildcard. |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1913 | Use this with extreme caution, since it is easy to mask a real |
| 1914 | programming error in this way! |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1915 | |
| 1916 | When an exception occurs, it may have an associated value, also known as |
| 1917 | the exceptions's |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1918 | {\em argument}. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1919 | The presence and type of the argument depend on the exception type. |
| 1920 | For exception types which have an argument, the except clause may |
| 1921 | specify a variable after the exception name (or list) to receive the |
| 1922 | argument's value, as follows: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1923 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1924 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1925 | >>> try: |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1926 | ... spam() |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1927 | ... except NameError, x: |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1928 | ... print 'name', x, 'undefined' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1929 | ... |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 1930 | name spam undefined |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1931 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1932 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1933 | % |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1934 | 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] | 1935 | (`detail') of the message for unhandled exceptions. |
| 1936 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1937 | Exception handlers don't just handle exceptions if they occur |
| 1938 | immediately in the try clause, but also if they occur inside functions |
| 1939 | that are called (even indirectly) in the try clause. |
| 1940 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1941 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1942 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1943 | >>> def this_fails(): |
| 1944 | ... x = 1/0 |
| 1945 | ... |
| 1946 | >>> try: |
| 1947 | ... this_fails() |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1948 | ... except ZeroDivisionError, detail: |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1949 | ... print 'Handling run-time error:', detail |
| 1950 | ... |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1951 | Handling run-time error: integer division or modulo |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1952 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1953 | \end{verbatim}\ecode |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1954 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1955 | \section{Raising Exceptions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1956 | |
| 1957 | The {\tt raise} statement allows the programmer to force a specified |
| 1958 | exception to occur. |
| 1959 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1960 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1961 | \bcode\begin{verbatim} |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1962 | >>> raise NameError, 'HiThere' |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1963 | Traceback (innermost last): |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 1964 | File "<stdin>", line 1 |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1965 | NameError: HiThere |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1966 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1967 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1968 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1969 | The first argument to {\tt raise} names the exception to be raised. |
| 1970 | The optional second argument specifies the exception's argument. |
| 1971 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1972 | \section{User-defined Exceptions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1973 | |
| 1974 | Programs may name their own exceptions by assigning a string to a |
| 1975 | variable. |
| 1976 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1977 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1978 | \bcode\begin{verbatim} |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1979 | >>> my_exc = 'my_exc' |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1980 | >>> try: |
| 1981 | ... raise my_exc, 2*2 |
| 1982 | ... except my_exc, val: |
Guido van Rossum | 67fa160 | 1991-04-23 14:14:57 +0000 | [diff] [blame] | 1983 | ... print 'My exception occurred, value:', val |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1984 | ... |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1985 | My exception occurred, value: 4 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1986 | >>> raise my_exc, 1 |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 1987 | Traceback (innermost last): |
| 1988 | File "<stdin>", line 1 |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 1989 | my_exc: 1 |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1990 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 1991 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 1992 | % |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1993 | Many standard modules use this to report errors that may occur in |
| 1994 | functions they define. |
| 1995 | |
Guido van Rossum | 6fc178f | 1991-08-16 09:13:42 +0000 | [diff] [blame] | 1996 | \section{Defining Clean-up Actions} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 1997 | |
| 1998 | The {\tt try} statement has another optional clause which is intended to |
| 1999 | define clean-up actions that must be executed under all circumstances. |
| 2000 | For example: |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2001 | |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 2002 | \bcode\begin{verbatim} |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2003 | >>> try: |
| 2004 | ... raise KeyboardInterrupt |
| 2005 | ... finally: |
| 2006 | ... print 'Goodbye, world!' |
| 2007 | ... |
| 2008 | Goodbye, world! |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2009 | Traceback (innermost last): |
Guido van Rossum | 2292b8e | 1991-01-23 16:31:24 +0000 | [diff] [blame] | 2010 | File "<stdin>", line 2 |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 2011 | KeyboardInterrupt |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2012 | >>> |
Guido van Rossum | 5ce78f1 | 1991-01-25 13:27:18 +0000 | [diff] [blame] | 2013 | \end{verbatim}\ecode |
Guido van Rossum | a8d754e | 1992-01-07 16:44:35 +0000 | [diff] [blame] | 2014 | % |
Guido van Rossum | da8c3fd | 1992-08-09 13:55:25 +0000 | [diff] [blame] | 2015 | A {\tt finally} clause is executed whether or not an exception has |
| 2016 | occurred in the {\tt try} clause. When an exception has occurred, it |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2017 | is re-raised after the {\tt finally} clause is executed. The |
Guido van Rossum | da8c3fd | 1992-08-09 13:55:25 +0000 | [diff] [blame] | 2018 | {\tt finally} clause is also executed ``on the way out'' when the |
| 2019 | {\tt try} statement is left via a {\tt break} or {\tt return} |
| 2020 | statement. |
| 2021 | |
| 2022 | A {\tt try} statement must either have one or more {\tt except} |
| 2023 | clauses or one {\tt finally} clause, but not both. |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 2024 | |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2025 | |
| 2026 | \chapter{Classes} |
| 2027 | |
| 2028 | Python's class mechanism adds classes to the language with a minimum |
| 2029 | 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] | 2030 | 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] | 2031 | do not put an absolute barrier between definition and user, but rather |
| 2032 | rely on the politeness of the user not to ``break into the |
| 2033 | definition.'' The most important features of classes are retained |
| 2034 | with full power, however: the class inheritance mechanism allows |
| 2035 | multiple base classes, a derived class can override any methods of its |
| 2036 | base class(es), a method can call the method of a base class with the |
| 2037 | same name. Objects can contain an arbitrary amount of private data. |
| 2038 | |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2039 | In \Cpp{} terminology, all class members (including the data members) are |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2040 | {\em public}, and all member functions are {\em virtual}. There are |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2041 | 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] | 2042 | shorthands for referencing the object's members from its methods: the |
| 2043 | method function is declared with an explicit first argument |
| 2044 | representing the object, which is provided implicitly by the call. As |
| 2045 | in Smalltalk, classes themselves are objects, albeit in the wider |
| 2046 | sense of the word: in Python, all data types are objects. This |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2047 | provides semantics for importing and renaming. But, just like in \Cpp{} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2048 | or Modula-3, built-in types cannot be used as base classes for |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2049 | 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] | 2050 | built-in operators with special syntax (arithmetic operators, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2051 | subscripting etc.) can be redefined for class members. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2052 | |
| 2053 | |
| 2054 | \section{A word about terminology} |
| 2055 | |
| 2056 | Lacking universally accepted terminology to talk about classes, I'll |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2057 | make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3 |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2058 | terms, since its object-oriented semantics are closer to those of |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2059 | 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] | 2060 | |
| 2061 | I also have to warn you that there's a terminological pitfall for |
| 2062 | object-oriented readers: the word ``object'' in Python does not |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2063 | necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2064 | Smalltalk, not all types in Python are classes: the basic built-in |
| 2065 | types like integers and lists aren't, and even somewhat more exotic |
| 2066 | types like files aren't. However, {\em all} Python types share a little |
| 2067 | bit of common semantics that is best described by using the word |
| 2068 | object. |
| 2069 | |
| 2070 | Objects have individuality, and multiple names (in multiple scopes) |
| 2071 | can be bound to the same object. This is known as aliasing in other |
| 2072 | languages. This is usually not appreciated on a first glance at |
| 2073 | Python, and can be safely ignored when dealing with immutable basic |
| 2074 | types (numbers, strings, tuples). However, aliasing has an |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2075 | (intended!) effect on the semantics of Python code involving mutable |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2076 | objects such as lists, dictionaries, and most types representing |
| 2077 | entities outside the program (files, windows, etc.). This is usually |
| 2078 | used to the benefit of the program, since aliases behave like pointers |
| 2079 | in some respects. For example, passing an object is cheap since only |
| 2080 | a pointer is passed by the implementation; and if a function modifies |
| 2081 | an object passed as an argument, the caller will see the change --- this |
| 2082 | obviates the need for two different argument passing mechanisms as in |
| 2083 | Pascal. |
| 2084 | |
| 2085 | |
| 2086 | \section{Python scopes and name spaces} |
| 2087 | |
| 2088 | Before introducing classes, I first have to tell you something about |
| 2089 | Python's scope rules. Class definitions play some neat tricks with |
| 2090 | name spaces, and you need to know how scopes and name spaces work to |
| 2091 | fully understand what's going on. Incidentally, knowledge about this |
| 2092 | subject is useful for any advanced Python programmer. |
| 2093 | |
| 2094 | Let's begin with some definitions. |
| 2095 | |
| 2096 | A {\em name space} is a mapping from names to objects. Most name |
| 2097 | spaces are currently implemented as Python dictionaries, but that's |
| 2098 | normally not noticeable in any way (except for performance), and it |
| 2099 | may change in the future. Examples of name spaces are: the set of |
| 2100 | built-in names (functions such as \verb\abs()\, and built-in exception |
| 2101 | names); the global names in a module; and the local names in a |
| 2102 | function invocation. In a sense the set of attributes of an object |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 2103 | also form a name space. The important thing to know about name |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2104 | spaces is that there is absolutely no relation between names in |
| 2105 | different name spaces; for instance, two different modules may both |
| 2106 | define a function ``maximize'' without confusion --- users of the |
| 2107 | modules must prefix it with the module name. |
| 2108 | |
| 2109 | By the way, I use the word {\em attribute} for any name following a |
| 2110 | dot --- for example, in the expression \verb\z.real\, \verb\real\ is |
| 2111 | an attribute of the object \verb\z\. Strictly speaking, references to |
| 2112 | names in modules are attribute references: in the expression |
| 2113 | \verb\modname.funcname\, \verb\modname\ is a module object and |
| 2114 | \verb\funcname\ is an attribute of it. In this case there happens to |
| 2115 | be a straightforward mapping between the module's attributes and the |
| 2116 | global names defined in the module: they share the same name space!% |
| 2117 | \footnote{ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2118 | Except for one thing. Module objects have a secret read-only |
| 2119 | attribute called {\tt __dict__} which returns the dictionary |
| 2120 | used to implement the module's name space; the name |
| 2121 | {\tt __dict__} is an attribute but not a global name. |
| 2122 | Obviously, using this violates the abstraction of name space |
| 2123 | implementation, and should be restricted to things like |
| 2124 | post-mortem debuggers... |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2125 | } |
| 2126 | |
| 2127 | Attributes may be read-only or writable. In the latter case, |
| 2128 | assignment to attributes is possible. Module attributes are writable: |
| 2129 | you can write \verb\modname.the_answer = 42\. Writable attributes may |
| 2130 | also be deleted with the del statement, e.g. |
| 2131 | \verb\del modname.the_answer\. |
| 2132 | |
| 2133 | Name spaces are created at different moments and have different |
| 2134 | lifetimes. The name space containing the built-in names is created |
| 2135 | when the Python interpreter starts up, and is never deleted. The |
| 2136 | global name space for a module is created when the module definition |
| 2137 | is read in; normally, module name spaces also last until the |
| 2138 | interpreter quits. The statements executed by the top-level |
| 2139 | invocation of the interpreter, either read from a script file or |
| 2140 | interactively, are considered part of a module called \verb\__main__\, |
| 2141 | so they have their own global name space. (The built-in names |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 2142 | actually also live in a module; this is called \verb\__builtin__\.) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2143 | |
| 2144 | The local name space for a function is created when the function is |
| 2145 | called, and deleted when the function returns or raises an exception |
| 2146 | that is not handled within the function. (Actually, forgetting would |
| 2147 | be a better way to describe what actually happens.) Of course, |
| 2148 | recursive invocations each have their own local name space. |
| 2149 | |
| 2150 | A {\em scope} is a textual region of a Python program where a name space |
| 2151 | is directly accessible. ``Directly accessible'' here means that an |
| 2152 | unqualified reference to a name attempts to find the name in the name |
| 2153 | space. |
| 2154 | |
| 2155 | Although scopes are determined statically, they are used dynamically. |
| 2156 | At any time during execution, exactly three nested scopes are in use |
| 2157 | (i.e., exactly three name spaces are directly accessible): the |
| 2158 | innermost scope, which is searched first, contains the local names, |
| 2159 | the middle scope, searched next, contains the current module's global |
| 2160 | names, and the outermost scope (searched last) is the name space |
| 2161 | containing built-in names. |
| 2162 | |
| 2163 | Usually, the local scope references the local names of the (textually) |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 2164 | current function. Outside of functions, the local scope references |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2165 | the same name space as the global scope: the module's name space. |
| 2166 | Class definitions place yet another name space in the local scope. |
| 2167 | |
| 2168 | It is important to realize that scopes are determined textually: the |
| 2169 | global scope of a function defined in a module is that module's name |
| 2170 | space, no matter from where or by what alias the function is called. |
| 2171 | On the other hand, the actual search for names is done dynamically, at |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 2172 | run time --- however, the language definition is evolving towards |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2173 | static name resolution, at ``compile'' time, so don't rely on dynamic |
| 2174 | name resolution! (In fact, local variables are already determined |
| 2175 | statically.) |
| 2176 | |
| 2177 | A special quirk of Python is that assignments always go into the |
| 2178 | innermost scope. Assignments do not copy data --- they just |
| 2179 | bind names to objects. The same is true for deletions: the statement |
| 2180 | \verb\del x\ removes the binding of x from the name space referenced by the |
| 2181 | local scope. In fact, all operations that introduce new names use the |
| 2182 | local scope: in particular, import statements and function definitions |
| 2183 | bind the module or function name in the local scope. (The |
| 2184 | \verb\global\ statement can be used to indicate that particular |
| 2185 | variables live in the global scope.) |
| 2186 | |
| 2187 | |
| 2188 | \section{A first look at classes} |
| 2189 | |
| 2190 | Classes introduce a little bit of new syntax, three new object types, |
| 2191 | and some new semantics. |
| 2192 | |
| 2193 | |
| 2194 | \subsection{Class definition syntax} |
| 2195 | |
| 2196 | The simplest form of class definition looks like this: |
| 2197 | |
| 2198 | \begin{verbatim} |
| 2199 | class ClassName: |
| 2200 | <statement-1> |
| 2201 | . |
| 2202 | . |
| 2203 | . |
| 2204 | <statement-N> |
| 2205 | \end{verbatim} |
| 2206 | |
| 2207 | Class definitions, like function definitions (\verb\def\ statements) |
| 2208 | must be executed before they have any effect. (You could conceivably |
| 2209 | place a class definition in a branch of an \verb\if\ statement, or |
| 2210 | inside a function.) |
| 2211 | |
| 2212 | In practice, the statements inside a class definition will usually be |
| 2213 | function definitions, but other statements are allowed, and sometimes |
| 2214 | useful --- we'll come back to this later. The function definitions |
| 2215 | inside a class normally have a peculiar form of argument list, |
| 2216 | dictated by the calling conventions for methods --- again, this is |
| 2217 | explained later. |
| 2218 | |
| 2219 | When a class definition is entered, a new name space is created, and |
| 2220 | used as the local scope --- thus, all assignments to local variables |
| 2221 | go into this new name space. In particular, function definitions bind |
| 2222 | the name of the new function here. |
| 2223 | |
| 2224 | When a class definition is left normally (via the end), a {\em class |
| 2225 | object} is created. This is basically a wrapper around the contents |
| 2226 | of the name space created by the class definition; we'll learn more |
| 2227 | about class objects in the next section. The original local scope |
| 2228 | (the one in effect just before the class definitions was entered) is |
| 2229 | reinstated, and the class object is bound here to class name given in |
| 2230 | the class definition header (ClassName in the example). |
| 2231 | |
| 2232 | |
| 2233 | \subsection{Class objects} |
| 2234 | |
| 2235 | Class objects support two kinds of operations: attribute references |
| 2236 | and instantiation. |
| 2237 | |
| 2238 | {\em Attribute references} use the standard syntax used for all |
| 2239 | attribute references in Python: \verb\obj.name\. Valid attribute |
| 2240 | names are all the names that were in the class's name space when the |
| 2241 | class object was created. So, if the class definition looked like |
| 2242 | this: |
| 2243 | |
| 2244 | \begin{verbatim} |
| 2245 | class MyClass: |
| 2246 | i = 12345 |
| 2247 | def f(x): |
| 2248 | return 'hello world' |
| 2249 | \end{verbatim} |
| 2250 | |
| 2251 | then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute |
| 2252 | references, returning an integer and a function object, respectively. |
| 2253 | Class attributes can also be assigned to, so you can change the |
| 2254 | value of \verb\MyClass.i\ by assignment. |
| 2255 | |
| 2256 | Class {\em instantiation} uses function notation. Just pretend that |
| 2257 | the class object is a parameterless function that returns a new |
| 2258 | instance of the class. For example, (assuming the above class): |
| 2259 | |
| 2260 | \begin{verbatim} |
| 2261 | x = MyClass() |
| 2262 | \end{verbatim} |
| 2263 | |
| 2264 | creates a new {\em instance} of the class and assigns this object to |
| 2265 | the local variable \verb\x\. |
| 2266 | |
| 2267 | |
| 2268 | \subsection{Instance objects} |
| 2269 | |
| 2270 | Now what can we do with instance objects? The only operations |
| 2271 | understood by instance objects are attribute references. There are |
| 2272 | two kinds of valid attribute names. |
| 2273 | |
| 2274 | The first I'll call {\em data attributes}. These correspond to |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2275 | ``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2276 | Data attributes need not be declared; like local variables, they |
| 2277 | spring into existence when they are first assigned to. For example, |
| 2278 | if \verb\x\ in the instance of \verb\MyClass\ created above, the |
| 2279 | following piece of code will print the value 16, without leaving a |
| 2280 | trace: |
| 2281 | |
| 2282 | \begin{verbatim} |
| 2283 | x.counter = 1 |
| 2284 | while x.counter < 10: |
| 2285 | x.counter = x.counter * 2 |
| 2286 | print x.counter |
| 2287 | del x.counter |
| 2288 | \end{verbatim} |
| 2289 | |
| 2290 | The second kind of attribute references understood by instance objects |
| 2291 | are {\em methods}. A method is a function that ``belongs to'' an |
| 2292 | object. (In Python, the term method is not unique to class instances: |
| 2293 | other object types can have methods as well, e.g., list objects have |
| 2294 | methods called append, insert, remove, sort, and so on. However, |
| 2295 | below, we'll use the term method exclusively to mean methods of class |
| 2296 | instance objects, unless explicitly stated otherwise.) |
| 2297 | |
| 2298 | Valid method names of an instance object depend on its class. By |
| 2299 | definition, all attributes of a class that are (user-defined) function |
| 2300 | objects define corresponding methods of its instances. So in our |
| 2301 | example, \verb\x.f\ is a valid method reference, since |
| 2302 | \verb\MyClass.f\ is a function, but \verb\x.i\ is not, since |
| 2303 | \verb\MyClass.i\ is not. But \verb\x.f\ is not the |
| 2304 | same thing as \verb\MyClass.f\ --- it is a {\em method object}, not a |
| 2305 | function object. |
| 2306 | |
| 2307 | |
| 2308 | \subsection{Method objects} |
| 2309 | |
| 2310 | Usually, a method is called immediately, e.g.: |
| 2311 | |
| 2312 | \begin{verbatim} |
| 2313 | x.f() |
| 2314 | \end{verbatim} |
| 2315 | |
| 2316 | In our example, this will return the string \verb\'hello world'\. |
| 2317 | However, it is not necessary to call a method right away: \verb\x.f\ |
| 2318 | is a method object, and can be stored away and called at a later |
| 2319 | moment, for example: |
| 2320 | |
| 2321 | \begin{verbatim} |
| 2322 | xf = x.f |
| 2323 | while 1: |
| 2324 | print xf() |
| 2325 | \end{verbatim} |
| 2326 | |
| 2327 | will continue to print \verb\hello world\ until the end of time. |
| 2328 | |
| 2329 | What exactly happens when a method is called? You may have noticed |
| 2330 | that \verb\x.f()\ was called without an argument above, even though |
| 2331 | the function definition for \verb\f\ specified an argument. What |
| 2332 | happened to the argument? Surely Python raises an exception when a |
| 2333 | function that requires an argument is called without any --- even if |
| 2334 | the argument isn't actually used... |
| 2335 | |
| 2336 | Actually, you may have guessed the answer: the special thing about |
| 2337 | methods is that the object is passed as the first argument of the |
| 2338 | function. In our example, the call \verb\x.f()\ is exactly equivalent |
| 2339 | to \verb\MyClass.f(x)\. In general, calling a method with a list of |
| 2340 | {\em n} arguments is equivalent to calling the corresponding function |
| 2341 | with an argument list that is created by inserting the method's object |
| 2342 | before the first argument. |
| 2343 | |
| 2344 | If you still don't understand how methods work, a look at the |
| 2345 | implementation can perhaps clarify matters. When an instance |
| 2346 | attribute is referenced that isn't a data attribute, its class is |
| 2347 | searched. If the name denotes a valid class attribute that is a |
| 2348 | function object, a method object is created by packing (pointers to) |
| 2349 | the instance object and the function object just found together in an |
| 2350 | abstract object: this is the method object. When the method object is |
| 2351 | called with an argument list, it is unpacked again, a new argument |
| 2352 | list is constructed from the instance object and the original argument |
| 2353 | list, and the function object is called with this new argument list. |
| 2354 | |
| 2355 | |
| 2356 | \section{Random remarks} |
| 2357 | |
| 2358 | |
| 2359 | [These should perhaps be placed more carefully...] |
| 2360 | |
| 2361 | |
| 2362 | Data attributes override method attributes with the same name; to |
| 2363 | avoid accidental name conflicts, which may cause hard-to-find bugs in |
| 2364 | large programs, it is wise to use some kind of convention that |
| 2365 | minimizes the chance of conflicts, e.g., capitalize method names, |
| 2366 | prefix data attribute names with a small unique string (perhaps just |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2367 | an underscore), or use verbs for methods and nouns for data attributes. |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2368 | |
| 2369 | |
| 2370 | Data attributes may be referenced by methods as well as by ordinary |
| 2371 | users (``clients'') of an object. In other words, classes are not |
| 2372 | usable to implement pure abstract data types. In fact, nothing in |
| 2373 | Python makes it possible to enforce data hiding --- it is all based |
| 2374 | upon convention. (On the other hand, the Python implementation, |
| 2375 | written in C, can completely hide implementation details and control |
| 2376 | access to an object if necessary; this can be used by extensions to |
| 2377 | Python written in C.) |
| 2378 | |
| 2379 | |
| 2380 | Clients should use data attributes with care --- clients may mess up |
| 2381 | invariants maintained by the methods by stamping on their data |
| 2382 | attributes. Note that clients may add data attributes of their own to |
| 2383 | an instance object without affecting the validity of the methods, as |
| 2384 | long as name conflicts are avoided --- again, a naming convention can |
| 2385 | save a lot of headaches here. |
| 2386 | |
| 2387 | |
| 2388 | There is no shorthand for referencing data attributes (or other |
| 2389 | methods!) from within methods. I find that this actually increases |
| 2390 | the readability of methods: there is no chance of confusing local |
| 2391 | variables and instance variables when glancing through a method. |
| 2392 | |
| 2393 | |
| 2394 | Conventionally, the first argument of methods is often called |
| 2395 | \verb\self\. This is nothing more than a convention: the name |
| 2396 | \verb\self\ has absolutely no special meaning to Python. (Note, |
| 2397 | however, that by not following the convention your code may be less |
| 2398 | readable by other Python programmers, and it is also conceivable that |
| 2399 | a {\em class browser} program be written which relies upon such a |
| 2400 | convention.) |
| 2401 | |
| 2402 | |
| 2403 | Any function object that is a class attribute defines a method for |
| 2404 | instances of that class. It is not necessary that the function |
| 2405 | definition is textually enclosed in the class definition: assigning a |
| 2406 | function object to a local variable in the class is also ok. For |
| 2407 | example: |
| 2408 | |
| 2409 | \begin{verbatim} |
| 2410 | # Function defined outside the class |
| 2411 | def f1(self, x, y): |
| 2412 | return min(x, x+y) |
| 2413 | |
| 2414 | class C: |
| 2415 | f = f1 |
| 2416 | def g(self): |
| 2417 | return 'hello world' |
| 2418 | h = g |
| 2419 | \end{verbatim} |
| 2420 | |
| 2421 | Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class |
| 2422 | \verb\C\ that refer to function objects, and consequently they are all |
| 2423 | methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent |
| 2424 | to \verb\g\. Note that this practice usually only serves to confuse |
| 2425 | the reader of a program. |
| 2426 | |
| 2427 | |
| 2428 | Methods may call other methods by using method attributes of the |
| 2429 | \verb\self\ argument, e.g.: |
| 2430 | |
| 2431 | \begin{verbatim} |
| 2432 | class Bag: |
| 2433 | def empty(self): |
| 2434 | self.data = [] |
| 2435 | def add(self, x): |
| 2436 | self.data.append(x) |
| 2437 | def addtwice(self, x): |
Guido van Rossum | 084b0b2 | 1992-08-14 09:19:56 +0000 | [diff] [blame] | 2438 | self.add(x) |
| 2439 | self.add(x) |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2440 | \end{verbatim} |
| 2441 | |
| 2442 | |
| 2443 | The instantiation operation (``calling'' a class object) creates an |
| 2444 | empty object. Many classes like to create objects in a known initial |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 2445 | state. Therefore a class may define a special method named |
| 2446 | \verb\__init__\, like this: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2447 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2448 | \begin{verbatim} |
| 2449 | def __init__(self): |
| 2450 | self.empty() |
| 2451 | \end{verbatim} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2452 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2453 | When a class defines an \verb\__init__\ method, class instantiation |
| 2454 | automatically invokes \verb\__init__\ for the newly-created class |
| 2455 | instance. So in the \verb\Bag\ example, a new and initialized instance |
| 2456 | can be obtained by: |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2457 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2458 | \begin{verbatim} |
| 2459 | x = Bag() |
| 2460 | \end{verbatim} |
| 2461 | |
| 2462 | Of course, the \verb\__init__\ method may have arguments for greater |
| 2463 | flexibility. In that case, arguments given to the class instantiation |
| 2464 | operator are passed on to \verb\__init__\. For example, |
| 2465 | |
| 2466 | \bcode\begin{verbatim} |
| 2467 | >>> class Complex: |
| 2468 | ... def __init__(self, realpart, imagpart): |
| 2469 | ... self.r = realpart |
| 2470 | ... self.i = imagpart |
| 2471 | ... |
| 2472 | >>> x = Complex(3.0,-4.5) |
| 2473 | >>> x.r, x.i |
| 2474 | (3.0, -4.5) |
| 2475 | >>> |
| 2476 | \end{verbatim}\ecode |
| 2477 | % |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2478 | Methods may reference global names in the same way as ordinary |
| 2479 | functions. The global scope associated with a method is the module |
| 2480 | containing the class definition. (The class itself is never used as a |
| 2481 | global scope!) While one rarely encounters a good reason for using |
| 2482 | global data in a method, there are many legitimate uses of the global |
| 2483 | scope: for one thing, functions and modules imported into the global |
| 2484 | scope can be used by methods, as well as functions and classes defined |
| 2485 | in it. Usually, the class containing the method is itself defined in |
| 2486 | this global scope, and in the next section we'll find some good |
| 2487 | reasons why a method would want to reference its own class! |
| 2488 | |
| 2489 | |
| 2490 | \section{Inheritance} |
| 2491 | |
| 2492 | Of course, a language feature would not be worthy of the name ``class'' |
| 2493 | without supporting inheritance. The syntax for a derived class |
| 2494 | definition looks as follows: |
| 2495 | |
| 2496 | \begin{verbatim} |
| 2497 | class DerivedClassName(BaseClassName): |
| 2498 | <statement-1> |
| 2499 | . |
| 2500 | . |
| 2501 | . |
| 2502 | <statement-N> |
| 2503 | \end{verbatim} |
| 2504 | |
| 2505 | The name \verb\BaseClassName\ must be defined in a scope containing |
| 2506 | the derived class definition. Instead of a base class name, an |
| 2507 | expression is also allowed. This is useful when the base class is |
| 2508 | defined in another module, e.g., |
| 2509 | |
| 2510 | \begin{verbatim} |
| 2511 | class DerivedClassName(modname.BaseClassName): |
| 2512 | \end{verbatim} |
| 2513 | |
| 2514 | Execution of a derived class definition proceeds the same as for a |
| 2515 | base class. When the class object is constructed, the base class is |
| 2516 | remembered. This is used for resolving attribute references: if a |
| 2517 | requested attribute is not found in the class, it is searched in the |
| 2518 | base class. This rule is applied recursively if the base class itself |
| 2519 | is derived from some other class. |
| 2520 | |
| 2521 | There's nothing special about instantiation of derived classes: |
| 2522 | \verb\DerivedClassName()\ creates a new instance of the class. Method |
| 2523 | references are resolved as follows: the corresponding class attribute |
| 2524 | is searched, descending down the chain of base classes if necessary, |
| 2525 | and the method reference is valid if this yields a function object. |
| 2526 | |
| 2527 | Derived classes may override methods of their base classes. Because |
| 2528 | methods have no special privileges when calling other methods of the |
| 2529 | same object, a method of a base class that calls another method |
| 2530 | 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] | 2531 | a derived class that overrides it. (For \Cpp{} programmers: all methods |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2532 | in Python are ``virtual functions''.) |
| 2533 | |
| 2534 | An overriding method in a derived class may in fact want to extend |
| 2535 | rather than simply replace the base class method of the same name. |
| 2536 | There is a simple way to call the base class method directly: just |
| 2537 | call \verb\BaseClassName.methodname(self, arguments)\. This is |
| 2538 | occasionally useful to clients as well. (Note that this only works if |
| 2539 | the base class is defined or imported directly in the global scope.) |
| 2540 | |
| 2541 | |
| 2542 | \subsection{Multiple inheritance} |
| 2543 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2544 | Python supports a limited form of multiple inheritance as well. A |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2545 | class definition with multiple base classes looks as follows: |
| 2546 | |
| 2547 | \begin{verbatim} |
| 2548 | class DerivedClassName(Base1, Base2, Base3): |
| 2549 | <statement-1> |
| 2550 | . |
| 2551 | . |
| 2552 | . |
| 2553 | <statement-N> |
| 2554 | \end{verbatim} |
| 2555 | |
| 2556 | The only rule necessary to explain the semantics is the resolution |
| 2557 | rule used for class attribute references. This is depth-first, |
| 2558 | left-to-right. Thus, if an attribute is not found in |
| 2559 | \verb\DerivedClassName\, it is searched in \verb\Base1\, then |
| 2560 | (recursively) in the base classes of \verb\Base1\, and only if it is |
| 2561 | not found there, it is searched in \verb\Base2\, and so on. |
| 2562 | |
Guido van Rossum | 95cd2ef | 1992-12-08 14:37:55 +0000 | [diff] [blame] | 2563 | (To some people breadth first---searching \verb\Base2\ and |
| 2564 | \verb\Base3\ before the base classes of \verb\Base1\---looks more |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2565 | natural. However, this would require you to know whether a particular |
| 2566 | attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in |
| 2567 | one of its base classes before you can figure out the consequences of |
| 2568 | a name conflict with an attribute of \verb\Base2\. The depth-first |
| 2569 | rule makes no differences between direct and inherited attributes of |
| 2570 | \verb\Base1\.) |
| 2571 | |
| 2572 | It is clear that indiscriminate use of multiple inheritance is a |
| 2573 | maintenance nightmare, given the reliance in Python on conventions to |
| 2574 | avoid accidental name conflicts. A well-known problem with multiple |
| 2575 | inheritance is a class derived from two classes that happen to have a |
| 2576 | common base class. While it is easy enough to figure out what happens |
| 2577 | in this case (the instance will have a single copy of ``instance |
| 2578 | variables'' or data attributes used by the common base class), it is |
| 2579 | not clear that these semantics are in any way useful. |
| 2580 | |
| 2581 | |
| 2582 | \section{Odds and ends} |
| 2583 | |
| 2584 | Sometimes it is useful to have a data type similar to the Pascal |
| 2585 | ``record'' or C ``struct'', bundling together a couple of named data |
| 2586 | items. An empty class definition will do nicely, e.g.: |
| 2587 | |
| 2588 | \begin{verbatim} |
| 2589 | class Employee: |
| 2590 | pass |
| 2591 | |
| 2592 | john = Employee() # Create an empty employee record |
| 2593 | |
| 2594 | # Fill the fields of the record |
| 2595 | john.name = 'John Doe' |
| 2596 | john.dept = 'computer lab' |
| 2597 | john.salary = 1000 |
| 2598 | \end{verbatim} |
| 2599 | |
| 2600 | |
| 2601 | A piece of Python code that expects a particular abstract data type |
| 2602 | can often be passed a class that emulates the methods of that data |
| 2603 | type instead. For instance, if you have a function that formats some |
| 2604 | data from a file object, you can define a class with methods |
| 2605 | \verb\read()\ and \verb\readline()\ that gets the data from a string |
| 2606 | buffer instead, and pass it as an argument. (Unfortunately, this |
| 2607 | technique has its limitations: a class can't define operations that |
| 2608 | are accessed by special syntax such as sequence subscripting or |
| 2609 | arithmetic operators, and assigning such a ``pseudo-file'' to |
| 2610 | \verb\sys.stdin\ will not cause the interpreter to read further input |
| 2611 | from it.) |
| 2612 | |
| 2613 | |
| 2614 | Instance method objects have attributes, too: \verb\m.im_self\ is the |
| 2615 | object of which the method is an instance, and \verb\m.im_func\ is the |
| 2616 | function object corresponding to the method. |
| 2617 | |
| 2618 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2619 | \chapter{Recent Additions} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 2620 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2621 | Python is an evolving language. Since this tutorial was last |
| 2622 | thoroughly revised, several new features have been added to the |
| 2623 | language. While ideally I should revise the tutorial to incorporate |
| 2624 | them in the mainline of the text, lack of time currently requires me |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 2625 | to take a more modest approach. In this chapter I will briefly list the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2626 | most important improvements to the language and how you can use them |
| 2627 | to your benefit. |
| 2628 | |
| 2629 | \section{The Last Printed Expression} |
| 2630 | |
| 2631 | In interactive mode, the last printed expression is assigned to the |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2632 | variable \code{_}. This means that when you are using Python as a |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2633 | desk calculator, it is somewhat easier to continue calculations, for |
| 2634 | example: |
| 2635 | |
| 2636 | \begin{verbatim} |
| 2637 | >>> tax = 17.5 / 100 |
| 2638 | >>> price = 3.50 |
| 2639 | >>> price * tax |
| 2640 | 0.6125 |
| 2641 | >>> price + _ |
| 2642 | 4.1125 |
| 2643 | >>> round(_, 2) |
| 2644 | 4.11 |
| 2645 | >>> |
| 2646 | \end{verbatim} |
| 2647 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2648 | For reasons too embarrassing to explain, this variable is implemented |
| 2649 | as a built-in (living in the module \code{__builtin__}), so it should |
| 2650 | be treated as read-only by the user. I.e. don't explicitly assign a |
| 2651 | value to it --- you would create an independent local variable with |
| 2652 | the same name masking the built-in variable with its magic behavior. |
| 2653 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2654 | \section{String Literals} |
| 2655 | |
| 2656 | \subsection{Double Quotes} |
| 2657 | |
| 2658 | Python can now also use double quotes to surround string literals, |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2659 | e.g. \verb\"this doesn't hurt a bit"\. There is no semantic |
| 2660 | difference between strings surrounded by single or double quotes. |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2661 | |
| 2662 | \subsection{Continuation Of String Literals} |
| 2663 | |
| 2664 | String literals can span multiple lines by escaping newlines with |
| 2665 | backslashes, e.g. |
| 2666 | |
| 2667 | \begin{verbatim} |
| 2668 | hello = "This is a rather long string containing\n\ |
| 2669 | several lines of text just as you would do in C.\n\ |
| 2670 | Note that whitespace at the beginning of the line is\ |
| 2671 | significant.\n" |
| 2672 | print hello |
| 2673 | \end{verbatim} |
| 2674 | |
| 2675 | which would print the following: |
| 2676 | \begin{verbatim} |
| 2677 | This is a rather long string containing |
| 2678 | several lines of text just as you would do in C. |
| 2679 | Note that whitespace at the beginning of the line is significant. |
| 2680 | \end{verbatim} |
| 2681 | |
| 2682 | \subsection{Triple-quoted strings} |
| 2683 | |
| 2684 | In some cases, when you need to include really long strings (e.g. |
| 2685 | containing several paragraphs of informational text), it is annoying |
| 2686 | that you have to terminate each line with \verb@\n\@, especially if |
| 2687 | you would like to reformat the text occasionally with a powerful text |
| 2688 | editor like Emacs. For such situations, ``triple-quoted'' strings can |
| 2689 | be used, e.g. |
| 2690 | |
| 2691 | \begin{verbatim} |
| 2692 | hello = """ |
| 2693 | |
| 2694 | This string is bounded by triple double quotes (3 times "). |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2695 | Unescaped newlines in the string are retained, though \ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2696 | it is still possible\nto use all normal escape sequences. |
| 2697 | |
| 2698 | Whitespace at the beginning of a line is |
| 2699 | significant. If you need to include three opening quotes |
| 2700 | you have to escape at least one of them, e.g. \""". |
| 2701 | |
| 2702 | This string ends in a newline. |
| 2703 | """ |
| 2704 | \end{verbatim} |
| 2705 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2706 | Triple-quoted strings can be surrounded by three single quotes as |
| 2707 | well, again without semantic difference. |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2708 | |
| 2709 | \subsection{String Literal Juxtaposition} |
| 2710 | |
| 2711 | One final twist: you can juxtapose multiple string literals. Two or |
| 2712 | more adjacent string literals (but not arbitrary expressions!) |
| 2713 | separated only by whitespace will be concatenated (without intervening |
| 2714 | whitespace) into a single string object at compile time. This makes |
| 2715 | it possible to continue a long string on the next line without |
| 2716 | sacrificing indentation or performance, unlike the use of the string |
| 2717 | concatenation operator \verb\+\ or the continuation of the literal |
| 2718 | itself on the next line (since leading whitespace is significant |
| 2719 | inside all types of string literals). Note that this feature, like |
| 2720 | all string features except triple-quoted strings, is borrowed from |
| 2721 | Standard C. |
| 2722 | |
| 2723 | \section{The Formatting Operator} |
| 2724 | |
| 2725 | \subsection{Basic Usage} |
| 2726 | |
| 2727 | The chapter on output formatting is really out of date: there is now |
| 2728 | an almost complete interface to C-style printf formats. This is done |
| 2729 | by overloading the modulo operator (\verb\%\) for a left operand |
| 2730 | which is a string, e.g. |
| 2731 | |
| 2732 | \begin{verbatim} |
| 2733 | >>> import math |
| 2734 | >>> print 'The value of PI is approximately %5.3f.' % math.pi |
| 2735 | The value of PI is approximately 3.142. |
| 2736 | >>> |
| 2737 | \end{verbatim} |
| 2738 | |
| 2739 | If there is more than one format in the string you pass a tuple as |
| 2740 | right operand, e.g. |
| 2741 | |
| 2742 | \begin{verbatim} |
| 2743 | >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| 2744 | >>> for name, phone in table.items(): |
| 2745 | ... print '%-10s ==> %10d' % (name, phone) |
| 2746 | ... |
| 2747 | Jack ==> 4098 |
| 2748 | Dcab ==> 8637678 |
| 2749 | Sjoerd ==> 4127 |
| 2750 | >>> |
| 2751 | \end{verbatim} |
| 2752 | |
| 2753 | Most formats work exactly as in C and require that you pass the proper |
| 2754 | type (however, if you don't you get an exception, not a core dump). |
| 2755 | The \verb\%s\ format is more relaxed: if the corresponding argument is |
| 2756 | not a string object, it is converted to string using the \verb\str()\ |
| 2757 | built-in function. Using \verb\*\ to pass the width or precision in |
| 2758 | as a separate (integer) argument is supported. The C formats |
| 2759 | \verb\%n\ and \verb\%p\ are not supported. |
| 2760 | |
| 2761 | \subsection{Referencing Variables By Name} |
| 2762 | |
| 2763 | If you have a really long format string that you don't want to split |
| 2764 | up, it would be nice if you could reference the variables to be |
| 2765 | formatted by name instead of by position. This can be done by using |
| 2766 | an extension of C formats using the form \verb\%(name)format\, e.g. |
| 2767 | |
| 2768 | \begin{verbatim} |
| 2769 | >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| 2770 | >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table |
| 2771 | Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
| 2772 | >>> |
| 2773 | \end{verbatim} |
| 2774 | |
| 2775 | This is particularly useful in combination with the new built-in |
| 2776 | \verb\vars()\ function, which returns a dictionary containing all |
| 2777 | local variables. |
| 2778 | |
| 2779 | \section{Optional Function Arguments} |
| 2780 | |
| 2781 | It is now possible to define functions with a variable number of |
| 2782 | arguments. There are two forms, which can be combined. |
| 2783 | |
| 2784 | \subsection{Default Argument Values} |
| 2785 | |
| 2786 | The most useful form is to specify a default value for one or more |
| 2787 | arguments. This creates a function that can be called with fewer |
| 2788 | arguments than it is defined, e.g. |
| 2789 | |
| 2790 | \begin{verbatim} |
| 2791 | def ask_ok(prompt, retries = 4, complaint = 'Yes or no, please!'): |
| 2792 | while 1: |
| 2793 | ok = raw_input(prompt) |
| 2794 | if ok in ('y', 'ye', 'yes'): return 1 |
| 2795 | if ok in ('n', 'no', 'nop', 'nope'): return 0 |
| 2796 | retries = retries - 1 |
| 2797 | if retries < 0: raise IOError, 'refusenik user' |
| 2798 | print complaint |
| 2799 | \end{verbatim} |
| 2800 | |
| 2801 | This function can be called either like this: |
| 2802 | \verb\ask_ok('Do you really want to quit?')\ or like this: |
| 2803 | \verb\ask_ok('OK to overwrite the file?', 2)\. |
| 2804 | |
| 2805 | The default values are evaluated at the point of function definition |
| 2806 | in the {\em defining} scope, so that e.g. |
| 2807 | |
| 2808 | \begin{verbatim} |
| 2809 | i = 5 |
| 2810 | def f(arg = i): print arg |
| 2811 | i = 6 |
| 2812 | f() |
| 2813 | \end{verbatim} |
| 2814 | |
| 2815 | will print \verb\5\. |
| 2816 | |
| 2817 | \subsection{Arbitrary Argument Lists} |
| 2818 | |
| 2819 | It is also possible to specify that a function can be called with an |
| 2820 | arbitrary number of arguments. These arguments will be wrapped up in |
| 2821 | a tuple. Before the variable number of arguments, zero or more normal |
| 2822 | arguments may occur, e.g. |
| 2823 | |
| 2824 | \begin{verbatim} |
| 2825 | def fprintf(file, format, *args): |
| 2826 | file.write(format % args) |
| 2827 | \end{verbatim} |
| 2828 | |
| 2829 | This feature may be combined with the previous, e.g. |
| 2830 | |
| 2831 | \begin{verbatim} |
| 2832 | def but_is_it_useful(required, optional = None, *remains): |
| 2833 | print "I don't know" |
| 2834 | \end{verbatim} |
| 2835 | |
| 2836 | \section{Lambda And Functional Programming Tools} |
| 2837 | |
| 2838 | \subsection{Lambda Forms} |
| 2839 | |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 2840 | By popular demand, a few features commonly found in functional |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2841 | programming languages and Lisp have been added to Python. With the |
| 2842 | \verb\lambda\ keyword, small anonymous functions can be created. |
| 2843 | Here's a function that returns the sum of its two arguments: |
| 2844 | \verb\lambda a, b: a+b\. Lambda forms can be used wherever function |
| 2845 | objects are required. They are syntactically restricted to a single |
| 2846 | expression. Semantically, they are just syntactic sugar for a normal |
| 2847 | function definition. Like nested function definitions, lambda forms |
| 2848 | cannot reference variables from the containing scope, but this can be |
| 2849 | overcome through the judicious use of default argument values, e.g. |
| 2850 | |
| 2851 | \begin{verbatim} |
| 2852 | def make_incrementor(n): |
Guido van Rossum | c1be9d5 | 1994-08-30 12:08:58 +0000 | [diff] [blame] | 2853 | return lambda x, incr=n: x+incr |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2854 | \end{verbatim} |
| 2855 | |
| 2856 | \subsection{Map, Reduce and Filter} |
| 2857 | |
| 2858 | Three new built-in functions on sequences are good candidate to pass |
| 2859 | lambda forms. |
| 2860 | |
| 2861 | \subsubsection{Map.} |
| 2862 | |
| 2863 | \verb\map(function, sequence)\ calls \verb\function(item)\ for each of |
| 2864 | the sequence's items and returns a list of the return values. For |
| 2865 | example, to compute some cubes: |
| 2866 | |
| 2867 | \begin{verbatim} |
| 2868 | >>> map(lambda x: x*x*x, range(1, 11)) |
| 2869 | [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000] |
| 2870 | >>> |
| 2871 | \end{verbatim} |
| 2872 | |
| 2873 | More than one sequence may be passed; the function must then have as |
| 2874 | many arguments as there are sequences and is called with the |
| 2875 | corresponding item from each sequence (or \verb\None\ if some sequence |
| 2876 | is shorter than another). If \verb\None\ is passed for the function, |
| 2877 | a function returning its argument(s) is substituted. |
| 2878 | |
| 2879 | Combining these two special cases, we see that |
| 2880 | \verb\map(None, list1, list2)\ is a convenient way of turning a pair |
| 2881 | of lists into a list of pairs. For example: |
| 2882 | |
| 2883 | \begin{verbatim} |
| 2884 | >>> seq = range(8) |
| 2885 | >>> map(None, seq, map(lambda x: x*x, seq)) |
| 2886 | [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)] |
| 2887 | >>> |
| 2888 | \end{verbatim} |
| 2889 | |
| 2890 | \subsubsection{Filter.} |
| 2891 | |
| 2892 | \verb\filter(function, sequence)\ returns a sequence (of the same |
| 2893 | type, if possible) consisting of those items from the sequence for |
| 2894 | which \verb\function(item)\ is true. For example, to compute some |
| 2895 | primes: |
| 2896 | |
| 2897 | \begin{verbatim} |
| 2898 | >>> filter(lambda x: x%2 != 0 and x%3 != 0, range(2, 25)) |
| 2899 | [5, 7, 11, 13, 17, 19, 23] |
| 2900 | >>> |
| 2901 | \end{verbatim} |
| 2902 | |
| 2903 | \subsubsection{Reduce.} |
| 2904 | |
| 2905 | \verb\reduce(function, sequence)\ returns a single value constructed |
| 2906 | by calling the (binary) function on the first two items of the |
| 2907 | sequence, then on the result and the next item, and so on. For |
| 2908 | example, to compute the sum of the numbers 1 through 10: |
| 2909 | |
| 2910 | \begin{verbatim} |
| 2911 | >>> reduce(lambda x, y: x+y, range(1, 11)) |
| 2912 | 55 |
| 2913 | >>> |
| 2914 | \end{verbatim} |
| 2915 | |
| 2916 | If there's only one item in the sequence, its value is returned; if |
| 2917 | the sequence is empty, an exception is raised. |
| 2918 | |
| 2919 | A third argument can be passed to indicate the starting value. In this |
| 2920 | case the starting value is returned for an empty sequence, and the |
| 2921 | function is first applied to the starting value and the first sequence |
| 2922 | item, then to the result and the next item, and so on. For example, |
| 2923 | |
| 2924 | \begin{verbatim} |
| 2925 | >>> def sum(seq): |
| 2926 | ... return reduce(lambda x, y: x+y, seq, 0) |
| 2927 | ... |
| 2928 | >>> sum(range(1, 11)) |
| 2929 | 55 |
| 2930 | >>> sum([]) |
| 2931 | 0 |
| 2932 | >>> |
| 2933 | \end{verbatim} |
| 2934 | |
| 2935 | \section{Continuation Lines Without Backslashes} |
| 2936 | |
| 2937 | While the general mechanism for continuation of a source line on the |
| 2938 | next physical line remains to place a backslash on the end of the |
| 2939 | line, expressions inside matched parentheses (or square brackets, or |
| 2940 | curly braces) can now also be continued without using a backslash. |
| 2941 | This is particularly useful for calls to functions with many |
| 2942 | arguments, and for initializations of large tables. |
| 2943 | |
| 2944 | For example: |
| 2945 | |
| 2946 | \begin{verbatim} |
| 2947 | month_names = ['Januari', 'Februari', 'Maart', |
| 2948 | 'April', 'Mei', 'Juni', |
| 2949 | 'Juli', 'Augustus', 'September', |
| 2950 | 'Oktober', 'November', 'December'] |
| 2951 | \end{verbatim} |
| 2952 | |
| 2953 | and |
| 2954 | |
| 2955 | \begin{verbatim} |
| 2956 | CopyInternalHyperLinks(self.context.hyperlinks, |
| 2957 | copy.context.hyperlinks, |
| 2958 | uidremap) |
| 2959 | \end{verbatim} |
| 2960 | |
| 2961 | \section{Regular Expressions} |
| 2962 | |
| 2963 | While C's printf-style output formats, transformed into Python, are |
| 2964 | adequate for most output formatting jobs, C's scanf-style input |
| 2965 | formats are not very powerful. Instead of scanf-style input, Python |
| 2966 | offers Emacs-style regular expressions as a powerful input and |
| 2967 | scanning mechanism. Read the corresponding section in the Library |
| 2968 | Reference for a full description. |
| 2969 | |
| 2970 | \section{Generalized Dictionaries} |
| 2971 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 2972 | The keys of dictionaries are no longer restricted to strings --- they |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 2973 | can be any immutable basic type including strings, numbers, tuples, or |
| 2974 | (certain) class instances. (Lists and dictionaries are not acceptable |
| 2975 | as dictionary keys, in order to avoid problems when the object used as |
| 2976 | a key is modified.) |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2977 | |
| 2978 | Dictionaries have two new methods: \verb\d.values()\ returns a list of |
| 2979 | the dictionary's values, and \verb\d.items()\ returns a list of the |
| 2980 | dictionary's (key, value) pairs. Like \verb\d.keys()\, these |
| 2981 | operations are slow for large dictionaries. Examples: |
| 2982 | |
| 2983 | \begin{verbatim} |
| 2984 | >>> d = {100: 'honderd', 1000: 'duizend', 10: 'tien'} |
| 2985 | >>> d.keys() |
| 2986 | [100, 10, 1000] |
| 2987 | >>> d.values() |
| 2988 | ['honderd', 'tien', 'duizend'] |
| 2989 | >>> d.items() |
| 2990 | [(100, 'honderd'), (10, 'tien'), (1000, 'duizend')] |
| 2991 | >>> |
| 2992 | \end{verbatim} |
| 2993 | |
| 2994 | \section{Miscellaneous New Built-in Functions} |
| 2995 | |
| 2996 | The function \verb\vars()\ returns a dictionary containing the current |
Guido van Rossum | 16cd7f9 | 1994-10-06 10:29:26 +0000 | [diff] [blame] | 2997 | local variables. With a module argument, it returns that module's |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 2998 | global variables. The old function \verb\dir(x)\ returns |
| 2999 | \verb\vars(x).keys()\. |
| 3000 | |
| 3001 | The function \verb\round(x)\ returns a floating point number rounded |
| 3002 | to the nearest integer (but still expressed as a floating point |
| 3003 | number). E.g. \verb\round(3.4) == 3.0\ and \verb\round(3.5) == 4.0\. |
| 3004 | With a second argument it rounds to the specified number of digits, |
| 3005 | e.g. \verb\round(math.pi, 4) == 3.1416\ or even |
| 3006 | \verb\round(123.4, -2) == 100.0\. |
| 3007 | |
| 3008 | The function \verb\hash(x)\ returns a hash value for an object. |
| 3009 | All object types acceptable as dictionary keys have a hash value (and |
| 3010 | it is this hash value that the dictionary implementation uses). |
| 3011 | |
| 3012 | The function \verb\id(x)\ return a unique identifier for an object. |
| 3013 | For two objects x and y, \verb\id(x) == id(y)\ if and only if |
| 3014 | \verb\x is y\. (In fact the object's address is used.) |
| 3015 | |
| 3016 | The function \verb\hasattr(x, name)\ returns whether an object has an |
| 3017 | attribute with the given name (a string value). The function |
| 3018 | \verb\getattr(x, name)\ returns the object's attribute with the given |
| 3019 | name. The function \verb\setattr(x, name, value)\ assigns a value to |
| 3020 | an object's attribute with the given name. These three functions are |
| 3021 | useful if the attribute names are not known beforehand. Note that |
Guido van Rossum | e5f8b60 | 1995-01-04 19:12:49 +0000 | [diff] [blame] | 3022 | \verb\getattr(x, 'spam')\ is equivalent to \verb\x.spam\, and |
| 3023 | \verb\setattr(x, 'spam', y)\ is equivalent to \verb\x.spam = y\. By |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 3024 | definition, \verb\hasattr(x, name)\ returns true if and only if |
| 3025 | \verb\getattr(x, name)\ returns without raising an exception. |
| 3026 | |
| 3027 | \section{Else Clause For Try Statement} |
| 3028 | |
| 3029 | The \verb\try...except\ statement now has an optional \verb\else\ |
| 3030 | clause, which must follow all \verb\except\ clauses. It is useful to |
| 3031 | place code that must be executed if the \verb\try\ clause does not |
| 3032 | raise an exception. For example: |
| 3033 | |
| 3034 | \begin{verbatim} |
| 3035 | for arg in sys.argv: |
| 3036 | try: |
| 3037 | f = open(arg, 'r') |
| 3038 | except IOError: |
| 3039 | print 'cannot open', arg |
| 3040 | else: |
| 3041 | print arg, 'has', len(f.readlines()), 'lines' |
| 3042 | f.close() |
| 3043 | \end{verbatim} |
Guido van Rossum | 5e0759d | 1992-08-07 16:06:24 +0000 | [diff] [blame] | 3044 | |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3045 | |
| 3046 | \section{New Class Features in Release 1.1} |
| 3047 | |
Guido van Rossum | cfb45e4 | 1994-11-10 23:04:43 +0000 | [diff] [blame] | 3048 | Some changes have been made to classes: the operator overloading |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3049 | mechanism is more flexible, providing more support for non-numeric use |
Guido van Rossum | 29766b2 | 1994-10-06 15:33:25 +0000 | [diff] [blame] | 3050 | of operators (including calling an object as if it were a function), |
| 3051 | and it is possible to trap attribute accesses. |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3052 | |
| 3053 | \subsection{New Operator Overloading} |
| 3054 | |
| 3055 | It is no longer necessary to coerce both sides of an operator to the |
| 3056 | same class or type. A class may still provide a \code{__coerce__} |
| 3057 | method, but this method may return objects of different types or |
| 3058 | classes if it feels like it. If no \code{__coerce__} is defined, any |
| 3059 | argument type or class is acceptable. |
| 3060 | |
| 3061 | In order to make it possible to implement binary operators where the |
| 3062 | right-hand side is a class instance but the left-hand side is not, |
| 3063 | without using coercions, right-hand versions of all binary operators |
| 3064 | may be defined. These have an `r' prepended to their name, |
| 3065 | e.g. \code{__radd__}. |
| 3066 | |
| 3067 | For example, here's a very simple class for representing times. Times |
| 3068 | are initialized from a number of seconds (like time.time()). Times |
Guido van Rossum | 1133aec | 1995-03-15 11:34:18 +0000 | [diff] [blame] | 3069 | are printed like this: \code{Wed Mar 15 12:28:48 1995}. Subtracting |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3070 | two Times gives their difference in seconds. Adding or subtracting a |
| 3071 | Time and a number gives a new Time. You can't add two times, nor can |
| 3072 | you subtract a Time from a number. |
| 3073 | |
| 3074 | \begin{verbatim} |
| 3075 | import time |
| 3076 | |
| 3077 | class Time: |
| 3078 | def __init__(self, seconds): |
| 3079 | self.seconds = seconds |
| 3080 | def __repr__(self): |
| 3081 | return time.ctime(self.seconds) |
| 3082 | def __add__(self, x): |
| 3083 | return Time(self.seconds + x) |
| 3084 | __radd__ = __add__ # support for x+t |
| 3085 | def __sub__(self, x): |
| 3086 | if hasattr(x, 'seconds'): # test if x could be a Time |
| 3087 | return self.seconds - x.seconds |
| 3088 | else: |
| 3089 | return self.seconds - x |
| 3090 | |
| 3091 | now = Time(time.time()) |
| 3092 | tomorrow = 24*3600 + now |
| 3093 | yesterday = now - today |
| 3094 | print tomorrow - yesterday # prints 172800 |
| 3095 | \end{verbatim} |
| 3096 | |
| 3097 | \subsection{Trapping Attribute Access} |
| 3098 | |
| 3099 | You can define three new ``magic'' methods in a class now: |
| 3100 | \code{__getattr__(self, name)}, \code{__setattr__(self, name, value)} |
| 3101 | and \code{__delattr__(self, name)}. |
| 3102 | |
| 3103 | The \code{__getattr__} method is called when an attribute access fails, |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 3104 | i.e. when an attribute access would otherwise raise AttributeError --- |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3105 | this is {\em after} the instance's dictionary and its class hierarchy |
| 3106 | have been searched for the named attribute. Note that if this method |
| 3107 | attempts to access any undefined instance attribute it will be called |
| 3108 | recursively! |
| 3109 | |
| 3110 | The \code{__setattr__} and \code{__delattr__} methods are called when |
| 3111 | assignment to, respectively deletion of an attribute are attempted. |
| 3112 | They are called {\em instead} of the normal action (which is to insert |
| 3113 | or delete the attribute in the instance dictionary). If either of |
| 3114 | these methods most set or delete any attribute, they can only do so by |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 3115 | using the instance dictionary directly --- \code{self.__dict__} --- else |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3116 | they would be called recursively. |
| 3117 | |
| 3118 | For example, here's a near-universal ``Wrapper'' class that passes all |
| 3119 | its attribute accesses to another object. Note how the |
| 3120 | \code{__init__} method inserts the wrapped object in |
| 3121 | \code{self.__dict__} in order to avoid endless recursion |
| 3122 | (\code{__setattr__} would call \code{__getattr__} which would call |
| 3123 | itself recursively). |
| 3124 | |
| 3125 | \begin{verbatim} |
| 3126 | class Wrapper: |
| 3127 | def __init__(self, wrapped): |
| 3128 | self.__dict__['wrapped'] = wrapped |
| 3129 | def __getattr__(self, name): |
| 3130 | return getattr(self.wrapped, name) |
| 3131 | def __setattr__(self, name, value): |
Guido van Rossum | cfb45e4 | 1994-11-10 23:04:43 +0000 | [diff] [blame] | 3132 | setattr(self.wrapped, name, value) |
Guido van Rossum | ca3f6c8 | 1994-10-06 14:08:53 +0000 | [diff] [blame] | 3133 | def __delattr__(self, name): |
| 3134 | delattr(self.wrapped, name) |
| 3135 | |
| 3136 | import sys |
| 3137 | f = Wrapper(sys.stdout) |
| 3138 | f.write('hello world\n') # prints 'hello world' |
| 3139 | \end{verbatim} |
| 3140 | |
Guido van Rossum | 29766b2 | 1994-10-06 15:33:25 +0000 | [diff] [blame] | 3141 | A simpler example of \code{__getattr__} is an attribute that is |
| 3142 | computed each time (or the first time) it it accessed. For instance: |
| 3143 | |
| 3144 | \begin{verbatim} |
| 3145 | from math import pi |
| 3146 | |
| 3147 | class Circle: |
| 3148 | def __init__(self, radius): |
| 3149 | self.radius = radius |
| 3150 | def __getattr__(self, name): |
| 3151 | if name == 'circumference': |
| 3152 | return 2 * pi * self.radius |
| 3153 | if name == 'diameter': |
| 3154 | return 2 * self.radius |
| 3155 | if name == 'area': |
| 3156 | return pi * pow(self.radius, 2) |
| 3157 | raise AttributeError, name |
| 3158 | \end{verbatim} |
| 3159 | |
| 3160 | \subsection{Calling a Class Instance} |
| 3161 | |
| 3162 | If a class defines a method \code{__call__} it is possible to call its |
| 3163 | instances as if they were functions. For example: |
| 3164 | |
| 3165 | \begin{verbatim} |
| 3166 | class PresetSomeArguments: |
| 3167 | def __init__(self, func, *args): |
| 3168 | self.func, self.args = func, args |
| 3169 | def __call__(self, *args): |
| 3170 | return apply(self.func, self.args + args) |
| 3171 | |
| 3172 | f = PresetSomeArguments(pow, 2) # f(i) computes powers of 2 |
| 3173 | for i in range(10): print f(i), # prints 1 2 4 8 16 32 64 128 256 512 |
| 3174 | print # append newline |
| 3175 | \end{verbatim} |
| 3176 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3177 | |
| 3178 | \chapter{New in Release 1.2} |
| 3179 | |
| 3180 | |
| 3181 | This chapter describes even more recent additions to the Python |
| 3182 | language and library. |
| 3183 | |
| 3184 | |
| 3185 | \section{New Class Features} |
| 3186 | |
| 3187 | The semantics of \code{__coerce__} have been changed to be more |
| 3188 | reasonable. As an example, the new standard module \code{Complex} |
| 3189 | implements fairly complete complex numbers using this. Additional |
| 3190 | examples of classes with and without \code{__coerce__} methods can be |
| 3191 | found in the \code{Demo/classes} subdirectory, modules \code{Rat} and |
| 3192 | \code{Dates}. |
| 3193 | |
| 3194 | If a class defines no \code{__coerce__} method, this is equivalent to |
| 3195 | the following definition: |
| 3196 | |
| 3197 | \begin{verbatim} |
| 3198 | def __coerce__(self, other): return self, other |
| 3199 | \end{verbatim} |
| 3200 | |
| 3201 | If \code{__coerce__} coerces itself to an object of a different type, |
| 3202 | the operation is carried out using that type --- in release 1.1, this |
| 3203 | would cause an error. |
| 3204 | |
| 3205 | Comparisons involving class instances now invoke \code{__coerce__} |
| 3206 | exactly as if \code{cmp(x, y)} were a binary operator like \code{+} |
| 3207 | (except if \code{x} and \code{y} are the same object). |
| 3208 | |
| 3209 | \section{Unix Signal Handling} |
| 3210 | |
Guido van Rossum | 34e1777 | 1996-06-10 19:44:49 +0000 | [diff] [blame^] | 3211 | On {\UNIX}, Python now supports signal handling. The module |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3212 | \code{signal} exports functions \code{signal}, \code{pause} and |
Guido van Rossum | 34e1777 | 1996-06-10 19:44:49 +0000 | [diff] [blame^] | 3213 | \code{alarm}, which act similar to their {\UNIX} counterparts. The |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3214 | module also exports the conventional names for the various signal |
| 3215 | classes (also usable with \code{os.kill()}) and \code{SIG_IGN} and |
| 3216 | \code{SIG_DFL}. See the section on \code{signal} in the Library |
| 3217 | Reference Manual for more information. |
| 3218 | |
| 3219 | \section{Exceptions Can Be Classes} |
| 3220 | |
| 3221 | User-defined exceptions are no longer limited to being string objects |
| 3222 | --- they can be identified by classes as well. Using this mechanism it |
| 3223 | is possible to create extensible hierarchies of exceptions. |
| 3224 | |
| 3225 | There are two new valid (semantic) forms for the raise statement: |
| 3226 | |
| 3227 | \begin{verbatim} |
| 3228 | raise Class, instance |
| 3229 | |
| 3230 | raise instance |
| 3231 | \end{verbatim} |
| 3232 | |
| 3233 | In the first form, \code{instance} must be an instance of \code{Class} |
| 3234 | or of a class derived from it. The second form is a shorthand for |
| 3235 | |
| 3236 | \begin{verbatim} |
| 3237 | raise instance.__class__, instance |
| 3238 | \end{verbatim} |
| 3239 | |
| 3240 | An except clause may list classes as well as string objects. A class |
| 3241 | in an except clause is compatible with an exception if it is the same |
| 3242 | class or a base class thereof (but not the other way around --- an |
| 3243 | except clause listing a derived class is not compatible with a base |
| 3244 | class). For example, the following code will print B, C, D in that |
| 3245 | order: |
| 3246 | |
| 3247 | \begin{verbatim} |
| 3248 | class B: |
| 3249 | pass |
| 3250 | class C(B): |
| 3251 | pass |
| 3252 | class D(C): |
| 3253 | pass |
| 3254 | |
| 3255 | for c in [B, C, D]: |
| 3256 | try: |
| 3257 | raise c() |
| 3258 | except D: |
| 3259 | print "D" |
| 3260 | except C: |
| 3261 | print "C" |
| 3262 | except B: |
| 3263 | print "B" |
| 3264 | \end{verbatim} |
| 3265 | |
| 3266 | Note that if the except clauses were reversed (with ``\code{except B}'' |
| 3267 | first), it would have printed B, B, B --- the first matching except |
| 3268 | clause is triggered. |
| 3269 | |
| 3270 | When an error message is printed for an unhandled exception which is a |
| 3271 | class, the class name is printed, then a colon and a space, and |
| 3272 | finally the instance converted to a string using the built-in function |
| 3273 | \code{str()}. |
| 3274 | |
| 3275 | In this release, the built-in exceptions are still strings. |
| 3276 | |
| 3277 | |
| 3278 | \section{Object Persistency and Object Copying} |
| 3279 | |
| 3280 | Two new modules, \code{pickle} and \code{shelve}, support storage and |
| 3281 | retrieval of (almost) arbitrary Python objects on disk, using the |
| 3282 | \code{dbm} package. A third module, \code{copy}, provides flexible |
Guido van Rossum | bcc9582 | 1995-02-16 16:28:48 +0000 | [diff] [blame] | 3283 | object copying operations. More information on these modules is |
| 3284 | provided in the Library Reference Manual. |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3285 | |
| 3286 | \subsection{Persistent Objects} |
| 3287 | |
| 3288 | The module \code{pickle} provides a general framework for objects to |
| 3289 | disassemble themselves into a stream of bytes and to reassemble such a |
| 3290 | stream back into an object. It copes with reference sharing, |
| 3291 | recursive objects and instances of user-defined classes, but not |
| 3292 | (directly) with objects that have ``magical'' links into the operating |
| 3293 | system such as open files, sockets or windows. |
| 3294 | |
| 3295 | The \code{pickle} module defines a simple protocol whereby |
| 3296 | user-defined classes can control how they are disassembled and |
| 3297 | assembled. The method \code{__getinitargs__()}, if defined, returns |
| 3298 | the argument list for the constructor to be used at assembly time (by |
| 3299 | default the constructor is called without arguments). The methods |
| 3300 | \code{__getstate__()} and \code{__setstate__()} are used to pass |
| 3301 | additional state from disassembly to assembly; by default the |
| 3302 | instance's \code{__dict__} is passed and restored. |
| 3303 | |
| 3304 | Note that \code{pickle} does not open or close any files --- it can be |
| 3305 | used equally well for moving objects around on a network or store them |
| 3306 | in a database. For ease of debugging, and the inevitable occasional |
| 3307 | manual patch-up, the constructed byte streams consist of printable |
Guido van Rossum | 47b4c0f | 1995-03-15 11:25:32 +0000 | [diff] [blame] | 3308 | \ASCII{} characters only (though it's not designed to be pretty). |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3309 | |
| 3310 | The module \code{shelve} provides a simple model for storing objects |
| 3311 | on files. The operation \code{shelve.open(filename)} returns a |
| 3312 | ``shelf'', which is a simple persistent database with a |
| 3313 | dictionary-like interface. Database keys are strings, objects stored |
| 3314 | in the database can be anything that \code{pickle} will handle. |
| 3315 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3316 | \subsection{Copying Objects} |
| 3317 | |
| 3318 | The module \code{copy} exports two functions: \code{copy()} and |
| 3319 | \code{deepcopy()}. The \code{copy()} function returns a ``shallow'' |
| 3320 | copy of an object; \code{deepcopy()} returns a ``deep'' copy. The |
| 3321 | difference between shallow and deep copying is only relevant for |
| 3322 | compound objects (objects that contain other objects, like lists or |
| 3323 | class instances): |
| 3324 | |
| 3325 | \begin{itemize} |
| 3326 | |
| 3327 | \item |
| 3328 | A shallow copy constructs a new compound object and then (to the |
| 3329 | extent possible) inserts {\em the same objects} into in that the |
| 3330 | original contains. |
| 3331 | |
| 3332 | \item |
| 3333 | A deep copy constructs a new compound object and then, recursively, |
| 3334 | inserts {\em copies} into it of the objects found in the original. |
| 3335 | |
| 3336 | \end{itemize} |
| 3337 | |
| 3338 | Both functions have the same restrictions and use the same protocols |
| 3339 | as \code{pickle} --- user-defined classes can control how they are |
| 3340 | copied by providing methods named \code{__getinitargs__()}, |
| 3341 | \code{__getstate__()} and \code{__setstate__()}. |
| 3342 | |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3343 | |
| 3344 | \section{Documentation Strings} |
| 3345 | |
| 3346 | A variety of objects now have a new attribute, \code{__doc__}, which |
| 3347 | is supposed to contain a documentation string (if no documentation is |
| 3348 | present, the attribute is \code{None}). New syntax, compatible with |
| 3349 | the old interpreter, allows for convenient initialization of the |
| 3350 | \code{__doc__} attribute of modules, classes and functions by placing |
| 3351 | a string literal by itself as the first statement in the suite. It |
| 3352 | must be a literal --- an expression yielding a string object is not |
| 3353 | accepted as a documentation string, since future tools may need to |
| 3354 | derive documentation from source by parsing. |
| 3355 | |
| 3356 | Here is a hypothetical, amply documented module called \code{Spam}: |
| 3357 | |
| 3358 | \begin{verbatim} |
| 3359 | """Spam operations. |
| 3360 | |
| 3361 | This module exports two classes, a function and an exception: |
| 3362 | |
| 3363 | class Spam: full Spam functionality --- three can sizes |
| 3364 | class SpamLight: limited Spam functionality --- only one can size |
| 3365 | |
| 3366 | def open(filename): open a file and return a corresponding Spam or |
| 3367 | SpamLight object |
| 3368 | |
| 3369 | GoneOff: exception raised for errors; should never happen |
| 3370 | |
| 3371 | Note that it is always possible to convert a SpamLight object to a |
| 3372 | Spam object by a simple method call, but that the reverse operation is |
| 3373 | generally costly and may fail for a number of reasons. |
| 3374 | """ |
| 3375 | |
| 3376 | class SpamLight: |
| 3377 | """Limited spam functionality. |
| 3378 | |
| 3379 | Supports a single can size, no flavor, and only hard disks. |
| 3380 | """ |
| 3381 | |
| 3382 | def __init__(self, size=12): |
| 3383 | """Construct a new SpamLight instance. |
| 3384 | |
| 3385 | Argument is the can size. |
| 3386 | """ |
| 3387 | # etc. |
| 3388 | |
| 3389 | # etc. |
| 3390 | |
| 3391 | class Spam(SpamLight): |
| 3392 | """Full spam functionality. |
| 3393 | |
| 3394 | Supports three can sizes, two flavor varieties, and all floppy |
| 3395 | disk formats still supported by current hardware. |
| 3396 | """ |
| 3397 | |
| 3398 | def __init__(self, size1=8, size2=12, size3=20): |
| 3399 | """Construct a new Spam instance. |
| 3400 | |
| 3401 | Arguments are up to three can sizes. |
| 3402 | """ |
| 3403 | # etc. |
| 3404 | |
| 3405 | # etc. |
| 3406 | |
| 3407 | def open(filename = "/dev/null"): |
| 3408 | """Open a can of Spam. |
| 3409 | |
| 3410 | Argument must be an existing file. |
| 3411 | """ |
| 3412 | # etc. |
| 3413 | |
| 3414 | class GoneOff: |
| 3415 | """Class used for Spam exceptions. |
| 3416 | |
| 3417 | There shouldn't be any. |
| 3418 | """ |
| 3419 | pass |
| 3420 | \end{verbatim} |
| 3421 | |
| 3422 | After executing ``\code{import Spam}'', the following expressions |
| 3423 | return the various documentation strings from the module: |
| 3424 | |
| 3425 | \begin{verbatim} |
| 3426 | Spam.__doc__ |
| 3427 | Spam.SpamLight.__doc__ |
| 3428 | Spam.SpamLight.__init__.__doc__ |
| 3429 | Spam.Spam.__doc__ |
| 3430 | Spam.Spam.__init__.__doc__ |
| 3431 | Spam.open.__doc__ |
| 3432 | Spam.GoneOff.__doc__ |
| 3433 | \end{verbatim} |
| 3434 | |
| 3435 | There are emerging conventions about the content and formatting of |
| 3436 | documentation strings. |
| 3437 | |
| 3438 | The first line should always be a short, concise summary of the |
| 3439 | object's purpose. For brevity, it should not explicitly state the |
| 3440 | object's name or type, since these are available by other means |
| 3441 | (except if the name happens to be a verb describing a function's |
| 3442 | operation). This line should begin with a capital letter and end with |
| 3443 | a period. |
| 3444 | |
| 3445 | If there are more lines in the documentation string, the second line |
| 3446 | should be blank, visually separating the summary from the rest of the |
| 3447 | description. The following lines should be one of more of paragraphs |
| 3448 | describing the objects calling conventions, its side effects, etc. |
| 3449 | |
| 3450 | Some people like to copy the Emacs convention of using UPPER CASE for |
| 3451 | function parameters --- this often saves a few words or lines. |
| 3452 | |
| 3453 | The Python parser does not strip indentation from multi-line string |
| 3454 | literals in Python, so tools that process documentation have to strip |
| 3455 | indentation. This is done using the following convention. The first |
| 3456 | non-blank line {\em after} the first line of the string determines the |
| 3457 | amount of indentation for the entire documentation string. (We can't |
| 3458 | use the first line since it is generally adjacent to the string's |
| 3459 | opening quotes so its indentation is not apparent in the string |
| 3460 | literal.) Whitespace ``equivalent'' to this indentation is then |
| 3461 | stripped from the start of all lines of the string. Lines that are |
| 3462 | indented less should not occur, but if they occur all their leading |
| 3463 | whitespace should be stripped. Equivalence of whitespace should be |
| 3464 | tested after expansion of tabs (to 8 spaces, normally). |
| 3465 | |
| 3466 | In this release, few of the built-in or standard functions and modules |
| 3467 | have documentation strings. |
| 3468 | |
| 3469 | |
| 3470 | \section{Customizing Import and Built-Ins} |
| 3471 | |
| 3472 | In preparation for a ``restricted execution mode'' which will be |
| 3473 | usable to run code received from an untrusted source (such as a WWW |
| 3474 | server or client), the mechanism by which modules are imported has |
| 3475 | been redesigned. It is now possible to provide your own function |
| 3476 | \code{__import__} which is called whenever an \code{import} statement |
| 3477 | is executed. There's a built-in function \code{__import__} which |
| 3478 | provides the default implementation, but more interesting, the various |
| 3479 | steps it takes are available separately from the new built-in module |
| 3480 | \code{imp}. (See the section on \code{imp} in the Library Reference |
Guido van Rossum | abfa2ca | 1995-07-07 22:57:02 +0000 | [diff] [blame] | 3481 | Manual for more information on this module -- it also contains a |
| 3482 | complete example of how to write your own \code{__import__} function.) |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3483 | |
| 3484 | When you do \code{dir()} in a fresh interactive interpreter you will |
| 3485 | see another ``secret'' object that's present in every module: |
| 3486 | \code{__builtins__}. This is either a dictionary or a module |
| 3487 | containing the set of built-in objects used by functions defined in |
| 3488 | current module. Although normally all modules are initialized with a |
| 3489 | reference to the same dictionary, it is now possible to use a |
| 3490 | different set of built-ins on a per-module basis. Together with the |
| 3491 | fact that the \code{import} statement uses the \code{__import__} |
| 3492 | function it finds in the importing modules' dictionary of built-ins, |
| 3493 | this forms the basis for a future restricted execution mode. |
| 3494 | |
| 3495 | |
| 3496 | \section{Python and the World-Wide Web} |
| 3497 | |
| 3498 | There is a growing number of modules available for writing WWW tools. |
| 3499 | The previous release already sported modules \code{gopherlib}, |
Guido van Rossum | bcc9582 | 1995-02-16 16:28:48 +0000 | [diff] [blame] | 3500 | \code{ftplib}, \code{httplib} and \code{urllib} (which unifies the |
| 3501 | other three) for accessing data through the commonest WWW protocols. |
| 3502 | This release also provides \code{cgi}, to ease the writing of |
| 3503 | server-side scripts that use the Common Gateway Interface protocol, |
| 3504 | supported by most WWW servers. The module \code{urlparse} provides |
| 3505 | precise parsing of a URL string into its components (address scheme, |
| 3506 | network location, path, parameters, query, and fragment identifier). |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3507 | |
Guido van Rossum | bcc9582 | 1995-02-16 16:28:48 +0000 | [diff] [blame] | 3508 | A rudimentary, parser for HTML files is available in the module |
| 3509 | \code{htmllib}. It currently supports a subset of HTML 1.0 (if you |
| 3510 | bring it up to date, I'd love to receive your fixes!). Unfortunately |
| 3511 | Python seems to be too slow for real-time parsing and formatting of |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 3512 | HTML such as required by interactive WWW browsers --- but it's good |
| 3513 | enough to write a ``robot'' (an automated WWW browser that searches |
| 3514 | the web for information). |
Guido van Rossum | 194e57c | 1995-02-15 15:51:38 +0000 | [diff] [blame] | 3515 | |
| 3516 | |
| 3517 | \section{Miscellaneous} |
| 3518 | |
| 3519 | \begin{itemize} |
| 3520 | |
| 3521 | \item |
| 3522 | The \code{socket} module now exports all the needed constants used for |
| 3523 | socket operations, such as \code{SO_BROADCAST}. |
| 3524 | |
| 3525 | \item |
| 3526 | The functions \code{popen()} and \code{fdopen()} in the \code{os} |
| 3527 | module now follow the pattern of the built-in function \code{open()}: |
| 3528 | the default mode argument is \code{'r'} and the optional third |
| 3529 | argument specifies the buffer size, where \code{0} means unbuffered, |
| 3530 | \code{1} means line-buffered, and any larger number means the size of |
| 3531 | the buffer in bytes. |
| 3532 | |
| 3533 | \end{itemize} |
| 3534 | |
| 3535 | |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3536 | \chapter{New in Release 1.3} |
| 3537 | |
| 3538 | |
| 3539 | This chapter describes yet more recent additions to the Python |
| 3540 | language and library. |
| 3541 | |
| 3542 | |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3543 | \section{Keyword Arguments} |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3544 | |
| 3545 | Functions and methods written in Python can now be called using |
| 3546 | keyword arguments of the form \code{\var{keyword} = \var{value}}. For |
| 3547 | instance, the following function: |
| 3548 | |
| 3549 | \begin{verbatim} |
| 3550 | def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'): |
| 3551 | print "-- This parrot wouldn't", action, |
| 3552 | print "if you put", voltage, "Volts through it." |
| 3553 | print "-- Lovely plumage, the", type |
| 3554 | print "-- It's", state, "!" |
| 3555 | \end{verbatim} |
| 3556 | |
| 3557 | could be called in any of the following ways: |
| 3558 | |
| 3559 | \begin{verbatim} |
| 3560 | parrot(1000) |
| 3561 | parrot(action = 'VOOOOOM', voltage = 1000000) |
| 3562 | parrot('a thousand', state = 'pushing up the daisies') |
| 3563 | parrot('a million', 'bereft of life', 'jump') |
| 3564 | \end{verbatim} |
| 3565 | |
| 3566 | but the following calls would all be invalid: |
| 3567 | |
| 3568 | \begin{verbatim} |
| 3569 | parrot() # required argument missing |
| 3570 | parrot(voltage=5.0, 'dead') # non-keyword argument following keyword |
| 3571 | parrot(110, voltage=220) # duplicate value for argument |
| 3572 | parrot(actor='John Cleese') # unknown keyword |
| 3573 | \end{verbatim} |
| 3574 | |
| 3575 | In general, an argument list must have the form: zero or more |
| 3576 | positional arguments followed by zero or more keyword arguments, where |
| 3577 | the keywords must be chosen from the formal parameter names. It's not |
| 3578 | important whether a formal parameter has a default value or not. No |
| 3579 | argument must receive a value more than once -- formal parameter names |
| 3580 | corresponding to positional arguments cannot be used as keywords in |
| 3581 | the same calls. |
| 3582 | |
| 3583 | Note that no special syntax is required to allow a function to be |
| 3584 | called with keyword arguments. The additional costs incurred by |
| 3585 | keyword arguments are only present when a call uses them. |
| 3586 | |
| 3587 | (As far as I know, these rules are exactly the same as used by |
| 3588 | Modula-3, even if they are enforced by totally different means. This |
| 3589 | is intentional.) |
| 3590 | |
| 3591 | When a final formal parameter of the form \code{**\var{name}} is |
| 3592 | present, it receives a dictionary containing all keyword arguments |
| 3593 | whose keyword doesn't correspond to a formal parameter. This may be |
| 3594 | combined with a formal parameter of the form \code{*\var{name}} which |
| 3595 | receives a tuple containing the positional arguments beyond the formal |
| 3596 | parameter list. (\code{*\var{name}} must occur before |
| 3597 | \code{**\var{name}}.) For example, if we define a function like this: |
| 3598 | |
| 3599 | \begin{verbatim} |
| 3600 | def cheeseshop(kind, *arguments, **keywords): |
| 3601 | print "-- Do you have any", kind, '?' |
| 3602 | print "-- I'm sorry, we're all out of", kind |
| 3603 | for arg in arguments: print arg |
| 3604 | print '-'*40 |
| 3605 | for kw in keywords.keys(): print kw, ':', keywords[kw] |
| 3606 | \end{verbatim} |
| 3607 | |
| 3608 | It could be called like this: |
| 3609 | |
| 3610 | \begin{verbatim} |
| 3611 | cheeseshop('Limburger', "It's very runny, sir.", |
| 3612 | "It's really very, VERY runny, sir.", |
| 3613 | client='John Cleese', |
| 3614 | shopkeeper='Michael Palin', |
| 3615 | sketch='Cheese Shop Sketch') |
| 3616 | \end{verbatim} |
| 3617 | |
| 3618 | and of course it would print: |
| 3619 | |
| 3620 | \begin{verbatim} |
| 3621 | -- Do you have any Limburger ? |
| 3622 | -- I'm sorry, we're all out of Limburger |
| 3623 | It's very runny, sir. |
| 3624 | It's really very, VERY runny, sir. |
| 3625 | ---------------------------------------- |
| 3626 | client : John Cleese |
| 3627 | shopkeeper : Michael Palin |
| 3628 | sketch : Cheese Shop Sketch |
| 3629 | \end{verbatim} |
| 3630 | |
Guido van Rossum | 691d4ec | 1995-10-08 01:14:57 +0000 | [diff] [blame] | 3631 | Consequences of this change include: |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3632 | |
| 3633 | \begin{itemize} |
| 3634 | |
| 3635 | \item |
Guido van Rossum | 691d4ec | 1995-10-08 01:14:57 +0000 | [diff] [blame] | 3636 | The built-in function \code{apply()} now has an optional third |
| 3637 | argument, which is a dictionary specifying any keyword arguments to be |
| 3638 | passed. For example, |
| 3639 | \begin{verbatim} |
| 3640 | apply(parrot, (), {'voltage': 20, 'action': 'voomm'}) |
| 3641 | \end{verbatim} |
| 3642 | is equivalent to |
| 3643 | \begin{verbatim} |
| 3644 | parrot(voltage=20, action='voomm') |
| 3645 | \end{verbatim} |
| 3646 | |
| 3647 | \item |
| 3648 | There is also a mechanism for functions and methods defined in an |
| 3649 | extension module (i.e., implemented in C or C++) to receive a |
| 3650 | dictionary of their keyword arguments. By default, such functions do |
| 3651 | not accept keyword arguments, since the argument names are not |
| 3652 | available to the interpreter. |
| 3653 | |
| 3654 | \item |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3655 | In the effort of implementing keyword arguments, function and |
| 3656 | especially method calls have been sped up significantly -- for a |
| 3657 | method with ten formal parameters, the call overhead has been cut in |
| 3658 | half; for a function with one formal parameters, the overhead has been |
| 3659 | reduced by a third. |
| 3660 | |
| 3661 | \item |
| 3662 | The format of \code{.pyc} files has changed (again). |
| 3663 | |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3664 | \item |
| 3665 | The \code{access} statement has been disabled. The syntax is still |
| 3666 | recognized but no code is generated for it. (There were some |
| 3667 | unpleasant interactions with changes for keyword arguments, and my |
| 3668 | plan is to get rid of \code{access} altogether in favor of a different |
| 3669 | approach.) |
| 3670 | |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3671 | \end{itemize} |
| 3672 | |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3673 | \section{Changes to the WWW and Internet tools} |
| 3674 | |
| 3675 | \begin{itemize} |
| 3676 | |
| 3677 | \item |
| 3678 | The \code{htmllib} module has been rewritten in an incompatible |
| 3679 | fashion. The new version is considerably more complete (HTML 2.0 |
| 3680 | except forms, but including all ISO-8859-1 entity definitions), and |
| 3681 | easy to use. Small changes to \code{sgmllib} have also been made, to |
| 3682 | better match the tokenization of HTML as recognized by other web |
| 3683 | tools. |
| 3684 | |
| 3685 | \item |
| 3686 | A new module \code{formatter} has been added, for use with the new |
| 3687 | \code{htmllib} module. |
| 3688 | |
| 3689 | \item |
| 3690 | The \code{urllib}and \code{httplib} modules have been changed somewhat |
| 3691 | to allow overriding unknown URL types and to support authentication. |
| 3692 | They now use \code{mimetools.Message} instead of \code{rfc822.Message} |
| 3693 | to parse headers. The \code{endrequest()} method has been removed |
| 3694 | from the HTTP class since it breaks the interaction with some servers. |
| 3695 | |
| 3696 | \item |
| 3697 | The \code{rfc822.Message} class has been changed to allow a flag to be |
| 3698 | passed in that says that the file is unseekable. |
| 3699 | |
| 3700 | \item |
| 3701 | The \code{ftplib} module has been fixed to be (hopefully) more robust |
| 3702 | on Linux. |
| 3703 | |
| 3704 | \item |
| 3705 | Several new operations that are optionally supported by servers have |
| 3706 | been added to \code{nntplib}: \code{xover}, \code{xgtitle}, |
| 3707 | \code{xpath} and \code{date}. % thanks to Kevan Heydon |
| 3708 | |
| 3709 | \end{itemize} |
| 3710 | |
| 3711 | \section{Other Language Changes} |
| 3712 | |
| 3713 | \begin{itemize} |
| 3714 | |
| 3715 | \item |
| 3716 | The \code{raise} statement now takes an optional argument which |
| 3717 | specifies the traceback to be used when printing the exception's stack |
| 3718 | trace. This must be a traceback object, such as found in |
| 3719 | \code{sys.exc_traceback}. When omitted or given as \code{None}, the |
| 3720 | old behavior (to generate a stack trace entry for the current stack |
| 3721 | frame) is used. |
| 3722 | |
| 3723 | \item |
| 3724 | The tokenizer is now more tolerant of alien whitespace. Control-L in |
| 3725 | the leading whitespace of a line resets the column number to zero, |
| 3726 | while Control-R just before the end of the line is ignored. |
| 3727 | |
| 3728 | \end{itemize} |
| 3729 | |
| 3730 | \section{Changes to Built-in Operations} |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3731 | |
| 3732 | \begin{itemize} |
| 3733 | |
| 3734 | \item |
| 3735 | For file objects, \code{\var{f}.read(0)} and |
| 3736 | \code{\var{f}.readline(0)} now return an empty string rather than |
| 3737 | reading an unlimited number of bytes. For the latter, omit the |
| 3738 | argument altogether or pass a negative value. |
| 3739 | |
| 3740 | \item |
| 3741 | A new system variable, \code{sys.platform}, has been added. It |
| 3742 | specifies the current platform, e.g. \code{sunos5} or \code{linux1}. |
| 3743 | |
| 3744 | \item |
| 3745 | The built-in functions \code{input()} and \code{raw_input()} now use |
| 3746 | the GNU readline library when it has been configured (formerly, only |
| 3747 | interactive input to the interpreter itself was read using GNU |
| 3748 | readline). The GNU readline library provides elaborate line editing |
| 3749 | and history. The Python debugger (\code{pdb}) is the first |
| 3750 | beneficiary of this change. |
| 3751 | |
| 3752 | \item |
| 3753 | Two new built-in functions, \code{globals()} and \code{locals()}, |
| 3754 | provide access to dictionaries containming current global and local |
| 3755 | variables, respectively. (These augment rather than replace |
| 3756 | \code{vars()}, which returns the current local variables when called |
| 3757 | without an argument, and a module's global variables when called with |
| 3758 | an argument of type module.) |
| 3759 | |
| 3760 | \item |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3761 | The built-in function \code{compile()} now takes a third possible |
| 3762 | value for the kind of code to be compiled: specifying \code{'single'} |
| 3763 | generates code for a single interactive statement, which prints the |
| 3764 | output of expression statements that evaluate to something else than |
| 3765 | \code{None}. |
| 3766 | |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3767 | \end{itemize} |
| 3768 | |
| 3769 | \section{Library Changes} |
| 3770 | |
| 3771 | \begin{itemize} |
| 3772 | |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3773 | \item |
Guido van Rossum | 691d4ec | 1995-10-08 01:14:57 +0000 | [diff] [blame] | 3774 | There are new module \code{ni} and \code{ihooks} that support |
| 3775 | importing modules with hierarchical names such as \code{A.B.C}. This |
| 3776 | is enabled by writing \code{import ni; ni.ni()} at the very top of the |
| 3777 | main program. These modules are amply documented in the Python |
| 3778 | source. |
| 3779 | |
| 3780 | \item |
| 3781 | The module \code{rexec} has been rewritten (incompatibly) to define a |
| 3782 | class and to use \code{ihooks}. |
| 3783 | |
| 3784 | \item |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3785 | The \code{string.split()} and \code{string.splitfields()} functions |
| 3786 | are now the same function (the presence or absence of the second |
| 3787 | argument determines which operation is invoked); similar for |
| 3788 | \code{string.join()} and \code{string.joinfields()}. |
| 3789 | |
| 3790 | \item |
| 3791 | The \code{Tkinter} module and its helper \code{Dialog} have been |
| 3792 | revamped to use keyword arguments. Tk 4.0 is now the standard. A new |
| 3793 | module \code{FileDialog} has been added which implements standard file |
| 3794 | selection dialogs. |
| 3795 | |
| 3796 | \item |
| 3797 | The optional built-in modules \code{dbm} and \code{gdbm} are more |
| 3798 | coordinated --- their \code{open()} functions now take the same values |
| 3799 | for their \var{flag} argument, and the \var{flag} and \var{mode} |
| 3800 | argument have default values (to open the database for reading only, |
| 3801 | and to create the database with mode \code{0666} minuse the umask, |
| 3802 | respectively). The memory leaks have finally been fixed. |
| 3803 | |
| 3804 | \item |
| 3805 | A new dbm-like module, \code{bsddb}, has been added, which uses the |
| 3806 | BSD DB package's hash method. % thanks to David Ely |
| 3807 | |
| 3808 | \item |
| 3809 | A portable (though slow) dbm-clone, implemented in Python, has been |
| 3810 | added for systems where none of the above is provided. It is aptly |
| 3811 | dubbed \code{dumbdbm}. |
| 3812 | |
| 3813 | \item |
| 3814 | The module \code{anydbm} provides a unified interface to \code{bsddb}, |
| 3815 | \code{gdbm}, \code{dbm}, and \code{dumbdbm}, choosing the first one |
| 3816 | available. |
| 3817 | |
| 3818 | \item |
| 3819 | A new extension module, \code{binascii}, provides a variety of |
| 3820 | operations for conversion of text-encoded binary data. |
| 3821 | |
| 3822 | \item |
| 3823 | There are three new or rewritten companion modules implemented in |
| 3824 | Python that can encode and decode the most common such formats: |
| 3825 | \code{uu} (uuencode), \code{base64} and \code{binhex}. |
| 3826 | |
| 3827 | \item |
| 3828 | A module to handle the MIME encoding quoted-printable has also been |
| 3829 | added: \code{quopri}. |
| 3830 | |
Guido van Rossum | aa93ca8 | 1995-10-11 17:47:45 +0000 | [diff] [blame] | 3831 | \item |
| 3832 | The parser module (which provides an interface to the Python parser's |
| 3833 | abstract syntax trees) has been rewritten (incompatibly) by Fred |
| 3834 | Drake. It now lets you change the parse tree and compile the result! |
| 3835 | |
Guido van Rossum | bf032a9 | 1995-10-11 19:28:39 +0000 | [diff] [blame] | 3836 | \item |
| 3837 | The \code{syslog} module has been upgraded and documented. |
| 3838 | % thanks to Steve Clift |
| 3839 | |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3840 | \end{itemize} |
| 3841 | |
| 3842 | \section{Other Changes} |
| 3843 | |
| 3844 | \begin{itemize} |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3845 | |
| 3846 | \item |
| 3847 | The dynamic module loader recognizes the fact that different filenames |
| 3848 | point to the same shared library and loads the library only once, so |
| 3849 | you can have a single shared library that defines multiple modules. |
| 3850 | (SunOS / SVR4 style shared libraries only.) |
| 3851 | |
| 3852 | \item |
| 3853 | Jim Fulton's ``abstract object interface'' has been incorporated into |
| 3854 | the run-time API. For more detailes, read the files |
| 3855 | \code{Include/abstract.h} and \code{Objects/abstract.c}. |
| 3856 | |
| 3857 | \item |
Guido van Rossum | 9beefa2 | 1995-10-08 00:38:51 +0000 | [diff] [blame] | 3858 | The Macintosh version is much more robust now. |
| 3859 | |
| 3860 | \item |
Guido van Rossum | eafe32a | 1995-08-10 14:18:10 +0000 | [diff] [blame] | 3861 | Numerous things I have forgotten or that are so obscure no-one will |
| 3862 | notice them anyway :-) |
| 3863 | |
| 3864 | \end{itemize} |
| 3865 | |
Guido van Rossum | d9bf55d | 1991-01-11 16:35:08 +0000 | [diff] [blame] | 3866 | \end{document} |