linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / tut / tut.tex
1 \documentclass{manual}
2 \usepackage[T1]{fontenc}
3 \usepackage{textcomp}
4
5 % Things to do:
6 % Should really move the Python startup file info to an appendix
7
8 \title{Python Tutorial}
9
10 \input{boilerplate}
11
12 \makeindex
13
14 \begin{document}
15
16 \maketitle
17
18 \ifhtml
19 \chapter*{Front Matter\label{front}}
20 \fi
21
22 \input{copyright}
23
24 \begin{abstract}
25
26 \noindent
27 Python is an easy to learn, powerful programming language.  It has
28 efficient high-level data structures and a simple but effective
29 approach to object-oriented programming.  Python's elegant syntax and
30 dynamic typing, together with its interpreted nature, make it an ideal 
31 language for scripting and rapid application development in many areas 
32 on most platforms.
33
34 The Python interpreter and the extensive standard library are freely
35 available in source or binary form for all major platforms from the
36 Python Web site, \url{http://www.python.org/}, and may be freely
37 distributed.  The same site also contains distributions of and
38 pointers to many free third party Python modules, programs and tools,
39 and additional documentation.
40
41 The Python interpreter is easily extended with new functions and data
42 types implemented in C or \Cpp{} (or other languages callable from C).
43 Python is also suitable as an extension language for customizable
44 applications.
45
46 This tutorial introduces the reader informally to the basic concepts
47 and features of the Python language and system.  It helps to have a
48 Python interpreter handy for hands-on experience, but all examples are
49 self-contained, so the tutorial can be read off-line as well.
50
51 For a description of standard objects and modules, see the
52 \citetitle[../lib/lib.html]{Python Library Reference} document.  The
53 \citetitle[../ref/ref.html]{Python Reference Manual} gives a more
54 formal definition of the language.  To write extensions in C or
55 \Cpp, read \citetitle[../ext/ext.html]{Extending and Embedding the
56 Python Interpreter} and \citetitle[../api/api.html]{Python/C API
57 Reference}.  There are also several books covering Python in depth.
58
59 This tutorial does not attempt to be comprehensive and cover every
60 single feature, or even every commonly used feature.  Instead, it
61 introduces many of Python's most noteworthy features, and will give
62 you a good idea of the language's flavor and style.  After reading it,
63 you will be able to read and write Python modules and programs, and
64 you will be ready to learn more about the various Python library
65 modules described in the \citetitle[../lib/lib.html]{Python Library
66 Reference}.
67
68 \end{abstract}
69
70 \tableofcontents
71
72
73 \chapter{Whetting Your Appetite \label{intro}}
74
75 If you ever wrote a large shell script, you probably know this
76 feeling: you'd love to add yet another feature, but it's already so
77 slow, and so big, and so complicated; or the feature involves a system
78 call or other function that is only accessible from C \ldots Usually
79 the problem at hand isn't serious enough to warrant rewriting the
80 script in C; perhaps the problem requires variable-length strings or
81 other data types (like sorted lists of file names) that are easy in
82 the shell but lots of work to implement in C, or perhaps you're not
83 sufficiently familiar with C.
84
85 Another situation: perhaps you have to work with several C libraries,
86 and the usual C write/compile/test/re-compile cycle is too slow.  You
87 need to develop software more quickly.  Possibly you've
88 written a program that could use an extension language, and you don't
89 want to design a language, write and debug an interpreter for it, then
90 tie it into your application.
91
92 In such cases, Python may be just the language for you.  Python is
93 simple to use, but it is a real programming language, offering much
94 more structure and support for large programs than the shell has.  On
95 the other hand, it also offers much more error checking than C, and,
96 being a \emph{very-high-level language}, it has high-level data types
97 built in, such as flexible arrays and dictionaries that would cost you
98 days to implement efficiently in C.  Because of its more general data
99 types Python is applicable to a much larger problem domain than
100 \emph{Awk} or even \emph{Perl}, yet many things are at least as easy
101 in Python as in those languages.
102
103 Python allows you to split your program in modules that can be
104 reused in other Python programs.  It comes with a large collection of
105 standard modules that you can use as the basis of your programs --- or
106 as examples to start learning to program in Python.  Some of these
107 modules provide things like file I/O, system calls,
108 sockets, and even interfaces to graphical user interface toolkits like Tk.  
109
110 Python is an interpreted language, which can save you considerable time
111 during program development because no compilation and linking is
112 necessary.  The interpreter can be used interactively, which makes it
113 easy to experiment with features of the language, to write throw-away
114 programs, or to test functions during bottom-up program development.
115 It is also a handy desk calculator.
116
117 Python enables programs to be written compactly and readably.  Programs
118 written in Python are typically much shorter than equivalent C or
119 \Cpp{} programs, for several reasons:
120 \begin{itemize}
121 \item
122 the high-level data types allow you to express complex operations in a
123 single statement;
124 \item
125 statement grouping is done by indentation instead of beginning and ending
126 brackets;
127 \item
128 no variable or argument declarations are necessary.
129 \end{itemize}
130
131 Python is \emph{extensible}: if you know how to program in C it is easy
132 to add a new built-in function or module to the interpreter, either to
133 perform critical operations at maximum speed, or to link Python
134 programs to libraries that may only be available in binary form (such
135 as a vendor-specific graphics library).  Once you are really hooked,
136 you can link the Python interpreter into an application written in C
137 and use it as an extension or command language for that application.
138
139 By the way, the language is named after the BBC show ``Monty Python's
140 Flying Circus'' and has nothing to do with nasty reptiles.  Making
141 references to Monty Python skits in documentation is not only allowed,
142 it is encouraged!
143
144 %\section{Where From Here \label{where}}
145
146 Now that you are all excited about Python, you'll want to examine it
147 in some more detail.  Since the best way to learn a language is
148 to use it, you are invited to do so with this tutorial.
149
150 In the next chapter, the mechanics of using the interpreter are
151 explained.  This is rather mundane information, but essential for
152 trying out the examples shown later.
153
154 The rest of the tutorial introduces various features of the Python
155 language and system through examples, beginning with simple
156 expressions, statements and data types, through functions and modules,
157 and finally touching upon advanced concepts like exceptions
158 and user-defined classes.
159
160 \chapter{Using the Python Interpreter \label{using}}
161
162 \section{Invoking the Interpreter \label{invoking}}
163
164 The Python interpreter is usually installed as
165 \file{/usr/local/bin/python} on those machines where it is available;
166 putting \file{/usr/local/bin} in your \UNIX{} shell's search path
167 makes it possible to start it by typing the command
168
169 \begin{verbatim}
170 python
171 \end{verbatim}
172
173 to the shell.  Since the choice of the directory where the interpreter
174 lives is an installation option, other places are possible; check with
175 your local Python guru or system administrator.  (E.g.,
176 \file{/usr/local/python} is a popular alternative location.)
177
178 Typing an end-of-file character (\kbd{Control-D} on \UNIX,
179 \kbd{Control-Z} on Windows) at the primary prompt causes the
180 interpreter to exit with a zero exit status.  If that doesn't work,
181 you can exit the interpreter by typing the following commands:
182 \samp{import sys; sys.exit()}.
183
184 The interpreter's line-editing features usually aren't very
185 sophisticated.  On \UNIX, whoever installed the interpreter may have
186 enabled support for the GNU readline library, which adds more
187 elaborate interactive editing and history features. Perhaps the
188 quickest check to see whether command line editing is supported is
189 typing Control-P to the first Python prompt you get.  If it beeps, you
190 have command line editing; see Appendix \ref{interacting} for an
191 introduction to the keys.  If nothing appears to happen, or if
192 \code{\^P} is echoed, command line editing isn't available; you'll
193 only be able to use backspace to remove characters from the current
194 line.
195
196 The interpreter operates somewhat like the \UNIX{} shell: when called
197 with standard input connected to a tty device, it reads and executes
198 commands interactively; when called with a file name argument or with
199 a file as standard input, it reads and executes a \emph{script} from
200 that file. 
201
202 A second way of starting the interpreter is
203 \samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which
204 executes the statement(s) in \var{command}, analogous to the shell's
205 \programopt{-c} option.  Since Python statements often contain spaces
206 or other characters that are special to the shell, it is best to quote 
207 \var{command} in its entirety with double quotes.
208
209 Some Python modules are also useful as scripts.  These can be invoked using
210 \samp{\program{python} \programopt{-m} \var{module} [arg] ...}, which
211 executes the source file for \var{module} as if you had spelled out its
212 full name on the command line.
213
214 Note that there is a difference between \samp{python file} and
215 \samp{python <file}.  In the latter case, input requests from the
216 program, such as calls to \function{input()} and \function{raw_input()}, are
217 satisfied from \emph{file}.  Since this file has already been read
218 until the end by the parser before the program starts executing, the
219 program will encounter end-of-file immediately.  In the former case
220 (which is usually what you want) they are satisfied from whatever file
221 or device is connected to standard input of the Python interpreter.
222
223 When a script file is used, it is sometimes useful to be able to run
224 the script and enter interactive mode afterwards.  This can be done by
225 passing \programopt{-i} before the script.  (This does not work if the
226 script is read from standard input, for the same reason as explained
227 in the previous paragraph.)
228
229 \subsection{Argument Passing \label{argPassing}}
230
231 When known to the interpreter, the script name and additional
232 arguments thereafter are passed to the script in the variable
233 \code{sys.argv}, which is a list of strings.  Its length is at least
234 one; when no script and no arguments are given, \code{sys.argv[0]} is
235 an empty string.  When the script name is given as \code{'-'} (meaning 
236 standard input), \code{sys.argv[0]} is set to \code{'-'}.  When
237 \programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to
238 \code{'-c'}.  When \programopt{-m} \var{module} is used, \code{sys.argv[0]} 
239 is set to the full name of the located module.  Options found after 
240 \programopt{-c} \var{command} or \programopt{-m} \var{module} are not consumed 
241 by the Python interpreter's option processing but left in \code{sys.argv} for 
242 the command or module to handle.
243
244 \subsection{Interactive Mode \label{interactive}}
245
246 When commands are read from a tty, the interpreter is said to be in
247 \emph{interactive mode}.  In this mode it prompts for the next command
248 with the \emph{primary prompt}, usually three greater-than signs
249 (\samp{>\code{>}>~}); for continuation lines it prompts with the
250 \emph{secondary prompt}, by default three dots (\samp{...~}).
251 The interpreter prints a welcome message stating its version number
252 and a copyright notice before printing the first prompt:
253
254 \begin{verbatim}
255 python
256 Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06)  [GCC 2.8.1] on sunos5
257 Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
258 >>>
259 \end{verbatim}
260
261 Continuation lines are needed when entering a multi-line construct.
262 As an example, take a look at this \keyword{if} statement:
263
264 \begin{verbatim}
265 >>> the_world_is_flat = 1
266 >>> if the_world_is_flat:
267 ...     print "Be careful not to fall off!"
268 ... 
269 Be careful not to fall off!
270 \end{verbatim}
271
272
273 \section{The Interpreter and Its Environment \label{interp}}
274
275 \subsection{Error Handling \label{error}}
276
277 When an error occurs, the interpreter prints an error
278 message and a stack trace.  In interactive mode, it then returns to
279 the primary prompt; when input came from a file, it exits with a
280 nonzero exit status after printing
281 the stack trace.  (Exceptions handled by an \keyword{except} clause in a
282 \keyword{try} statement are not errors in this context.)  Some errors are
283 unconditionally fatal and cause an exit with a nonzero exit; this
284 applies to internal inconsistencies and some cases of running out of
285 memory.  All error messages are written to the standard error stream;
286 normal output from executed commands is written to standard
287 output.
288
289 Typing the interrupt character (usually Control-C or DEL) to the
290 primary or secondary prompt cancels the input and returns to the
291 primary prompt.\footnote{
292         A problem with the GNU Readline package may prevent this.
293 }
294 Typing an interrupt while a command is executing raises the
295 \exception{KeyboardInterrupt} exception, which may be handled by a
296 \keyword{try} statement.
297
298 \subsection{Executable Python Scripts \label{scripts}}
299
300 On BSD'ish \UNIX{} systems, Python scripts can be made directly
301 executable, like shell scripts, by putting the line
302
303 \begin{verbatim}
304 #! /usr/bin/env python
305 \end{verbatim}
306
307 (assuming that the interpreter is on the user's \envvar{PATH}) at the
308 beginning of the script and giving the file an executable mode.  The
309 \samp{\#!} must be the first two characters of the file.  On some
310 platforms, this first line must end with a \UNIX-style line ending
311 (\character{\e n}), not a Mac OS (\character{\e r}) or Windows
312 (\character{\e r\e n}) line ending.  Note that
313 the hash, or pound, character, \character{\#}, is used to start a
314 comment in Python.
315
316 The script can be given a executable mode, or permission, using the
317 \program{chmod} command:
318
319 \begin{verbatim}
320 $ chmod +x myscript.py
321 \end{verbatim} % $ <-- bow to font-lock
322
323
324 \subsection{Source Code Encoding}
325
326 It is possible to use encodings different than \ASCII{} in Python source
327 files. The best way to do it is to put one more special comment line
328 right after the \code{\#!} line to define the source file encoding:
329
330 \begin{alltt}
331 # -*- coding: \var{encoding} -*- 
332 \end{alltt}
333
334 With that declaration, all characters in the source file will be treated as
335 having the encoding \var{encoding}, and it will be
336 possible to directly write Unicode string literals in the selected
337 encoding.  The list of possible encodings can be found in the
338 \citetitle[../lib/lib.html]{Python Library Reference}, in the section
339 on \ulink{\module{codecs}}{../lib/module-codecs.html}.
340
341 For example, to write Unicode literals including the Euro currency
342 symbol, the ISO-8859-15 encoding can be used, with the Euro symbol
343 having the ordinal value 164.  This script will print the value 8364
344 (the Unicode codepoint corresponding to the Euro symbol) and then
345 exit:
346
347 \begin{alltt}
348 # -*- coding: iso-8859-15 -*-
349
350 currency = u"\texteuro"
351 print ord(currency)
352 \end{alltt}
353
354 If your editor supports saving files as \code{UTF-8} with a UTF-8
355 \emph{byte order mark} (aka BOM), you can use that instead of an
356 encoding declaration. IDLE supports this capability if
357 \code{Options/General/Default Source Encoding/UTF-8} is set. Notice
358 that this signature is not understood in older Python releases (2.2
359 and earlier), and also not understood by the operating system for
360 script files with \code{\#!} lines (only used on \UNIX{} systems).
361
362 By using UTF-8 (either through the signature or an encoding
363 declaration), characters of most languages in the world can be used
364 simultaneously in string literals and comments.  Using non-\ASCII{}
365 characters in identifiers is not supported. To display all these
366 characters properly, your editor must recognize that the file is
367 UTF-8, and it must use a font that supports all the characters in the
368 file.
369
370 \subsection{The Interactive Startup File \label{startup}}
371
372 % XXX This should probably be dumped in an appendix, since most people
373 % don't use Python interactively in non-trivial ways.
374
375 When you use Python interactively, it is frequently handy to have some
376 standard commands executed every time the interpreter is started.  You
377 can do this by setting an environment variable named
378 \envvar{PYTHONSTARTUP} to the name of a file containing your start-up
379 commands.  This is similar to the \file{.profile} feature of the
380 \UNIX{} shells.
381
382 This file is only read in interactive sessions, not when Python reads
383 commands from a script, and not when \file{/dev/tty} is given as the
384 explicit source of commands (which otherwise behaves like an
385 interactive session).  It is executed in the same namespace where
386 interactive commands are executed, so that objects that it defines or
387 imports can be used without qualification in the interactive session.
388 You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in
389 this file.
390
391 If you want to read an additional start-up file from the current
392 directory, you can program this in the global start-up file using code
393 like \samp{if os.path.isfile('.pythonrc.py'):
394 execfile('.pythonrc.py')}.  If you want to use the startup file in a
395 script, you must do this explicitly in the script:
396
397 \begin{verbatim}
398 import os
399 filename = os.environ.get('PYTHONSTARTUP')
400 if filename and os.path.isfile(filename):
401     execfile(filename)
402 \end{verbatim}
403
404
405 \chapter{An Informal Introduction to Python \label{informal}}
406
407 In the following examples, input and output are distinguished by the
408 presence or absence of prompts (\samp{>\code{>}>~} and \samp{...~}): to repeat
409 the example, you must type everything after the prompt, when the
410 prompt appears; lines that do not begin with a prompt are output from
411 the interpreter. %
412 %\footnote{
413 %        I'd prefer to use different fonts to distinguish input
414 %        from output, but the amount of LaTeX hacking that would require
415 %        is currently beyond my ability.
416 %}
417 Note that a secondary prompt on a line by itself in an example means
418 you must type a blank line; this is used to end a multi-line command.
419
420 Many of the examples in this manual, even those entered at the
421 interactive prompt, include comments.  Comments in Python start with
422 the hash character, \character{\#}, and extend to the end of the
423 physical line.  A comment may appear at the start of a line or
424 following whitespace or code, but not within a string literal.  A hash 
425 character within a string literal is just a hash character.
426
427 Some examples:
428
429 \begin{verbatim}
430 # this is the first comment
431 SPAM = 1                 # and this is the second comment
432                          # ... and now a third!
433 STRING = "# This is not a comment."
434 \end{verbatim}
435
436
437 \section{Using Python as a Calculator \label{calculator}}
438
439 Let's try some simple Python commands.  Start the interpreter and wait
440 for the primary prompt, \samp{>\code{>}>~}.  (It shouldn't take long.)
441
442 \subsection{Numbers \label{numbers}}
443
444 The interpreter acts as a simple calculator: you can type an
445 expression at it and it will write the value.  Expression syntax is
446 straightforward: the operators \code{+}, \code{-}, \code{*} and
447 \code{/} work just like in most other languages (for example, Pascal
448 or C); parentheses can be used for grouping.  For example:
449
450 \begin{verbatim}
451 >>> 2+2
452 4
453 >>> # This is a comment
454 ... 2+2
455 4
456 >>> 2+2  # and a comment on the same line as code
457 4
458 >>> (50-5*6)/4
459 5
460 >>> # Integer division returns the floor:
461 ... 7/3
462 2
463 >>> 7/-3
464 -3
465 \end{verbatim}
466
467 The equal sign (\character{=}) is used to assign a value to a variable.
468 Afterwards, no result is displayed before the next interactive prompt:
469
470 \begin{verbatim}
471 >>> width = 20
472 >>> height = 5*9
473 >>> width * height
474 900
475 \end{verbatim}
476
477 A value can be assigned to several variables simultaneously:
478
479 \begin{verbatim}
480 >>> x = y = z = 0  # Zero x, y and z
481 >>> x
482 0
483 >>> y
484 0
485 >>> z
486 0
487 \end{verbatim}
488
489 There is full support for floating point; operators with mixed type
490 operands convert the integer operand to floating point:
491
492 \begin{verbatim}
493 >>> 3 * 3.75 / 1.5
494 7.5
495 >>> 7.0 / 2
496 3.5
497 \end{verbatim}
498
499 Complex numbers are also supported; imaginary numbers are written with
500 a suffix of \samp{j} or \samp{J}.  Complex numbers with a nonzero
501 real component are written as \samp{(\var{real}+\var{imag}j)}, or can
502 be created with the \samp{complex(\var{real}, \var{imag})} function.
503
504 \begin{verbatim}
505 >>> 1j * 1J
506 (-1+0j)
507 >>> 1j * complex(0,1)
508 (-1+0j)
509 >>> 3+1j*3
510 (3+3j)
511 >>> (3+1j)*3
512 (9+3j)
513 >>> (1+2j)/(1+1j)
514 (1.5+0.5j)
515 \end{verbatim}
516
517 Complex numbers are always represented as two floating point numbers,
518 the real and imaginary part.  To extract these parts from a complex
519 number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.  
520
521 \begin{verbatim}
522 >>> a=1.5+0.5j
523 >>> a.real
524 1.5
525 >>> a.imag
526 0.5
527 \end{verbatim}
528
529 The conversion functions to floating point and integer
530 (\function{float()}, \function{int()} and \function{long()}) don't
531 work for complex numbers --- there is no one correct way to convert a
532 complex number to a real number.  Use \code{abs(\var{z})} to get its
533 magnitude (as a float) or \code{z.real} to get its real part.
534
535 \begin{verbatim}
536 >>> a=3.0+4.0j
537 >>> float(a)
538 Traceback (most recent call last):
539   File "<stdin>", line 1, in ?
540 TypeError: can't convert complex to float; use abs(z)
541 >>> a.real
542 3.0
543 >>> a.imag
544 4.0
545 >>> abs(a)  # sqrt(a.real**2 + a.imag**2)
546 5.0
547 >>>
548 \end{verbatim}
549
550 In interactive mode, the last printed expression is assigned to the
551 variable \code{_}.  This means that when you are using Python as a
552 desk calculator, it is somewhat easier to continue calculations, for
553 example:
554
555 \begin{verbatim}
556 >>> tax = 12.5 / 100
557 >>> price = 100.50
558 >>> price * tax
559 12.5625
560 >>> price + _
561 113.0625
562 >>> round(_, 2)
563 113.06
564 >>>
565 \end{verbatim}
566
567 This variable should be treated as read-only by the user.  Don't
568 explicitly assign a value to it --- you would create an independent
569 local variable with the same name masking the built-in variable with
570 its magic behavior.
571
572 \subsection{Strings \label{strings}}
573
574 Besides numbers, Python can also manipulate strings, which can be
575 expressed in several ways.  They can be enclosed in single quotes or
576 double quotes:
577
578 \begin{verbatim}
579 >>> 'spam eggs'
580 'spam eggs'
581 >>> 'doesn\'t'
582 "doesn't"
583 >>> "doesn't"
584 "doesn't"
585 >>> '"Yes," he said.'
586 '"Yes," he said.'
587 >>> "\"Yes,\" he said."
588 '"Yes," he said.'
589 >>> '"Isn\'t," she said.'
590 '"Isn\'t," she said.'
591 \end{verbatim}
592
593 String literals can span multiple lines in several ways.  Continuation
594 lines can be used, with a backslash as the last character on the line
595 indicating that the next line is a logical continuation of the line:
596
597 \begin{verbatim}
598 hello = "This is a rather long string containing\n\
599 several lines of text just as you would do in C.\n\
600     Note that whitespace at the beginning of the line is\
601  significant."
602
603 print hello
604 \end{verbatim}
605
606 Note that newlines still need to be embedded in the string using
607 \code{\e n}; the newline following the trailing backslash is
608 discarded.  This example would print the following:
609
610 \begin{verbatim}
611 This is a rather long string containing
612 several lines of text just as you would do in C.
613     Note that whitespace at the beginning of the line is significant.
614 \end{verbatim}
615
616 If we make the string literal a ``raw'' string, however, the
617 \code{\e n} sequences are not converted to newlines, but the backslash
618 at the end of the line, and the newline character in the source, are
619 both included in the string as data.  Thus, the example:
620
621 \begin{verbatim}
622 hello = r"This is a rather long string containing\n\
623 several lines of text much as you would do in C."
624
625 print hello
626 \end{verbatim}
627
628 would print:
629
630 \begin{verbatim}
631 This is a rather long string containing\n\
632 several lines of text much as you would do in C.
633 \end{verbatim}
634
635 Or, strings can be surrounded in a pair of matching triple-quotes:
636 \code{"""} or \code{'\code{'}'}.  End of lines do not need to be escaped
637 when using triple-quotes, but they will be included in the string.
638
639 \begin{verbatim}
640 print """
641 Usage: thingy [OPTIONS] 
642      -h                        Display this usage message
643      -H hostname               Hostname to connect to
644 """
645 \end{verbatim}
646
647 produces the following output:
648
649 \begin{verbatim}
650 Usage: thingy [OPTIONS] 
651      -h                        Display this usage message
652      -H hostname               Hostname to connect to
653 \end{verbatim}
654
655 The interpreter prints the result of string operations in the same way
656 as they are typed for input: inside quotes, and with quotes and other
657 funny characters escaped by backslashes, to show the precise
658 value.  The string is enclosed in double quotes if the string contains
659 a single quote and no double quotes, else it's enclosed in single
660 quotes.  (The \keyword{print} statement, described later, can be used
661 to write strings without quotes or escapes.)
662
663 Strings can be concatenated (glued together) with the
664 \code{+} operator, and repeated with \code{*}:
665
666 \begin{verbatim}
667 >>> word = 'Help' + 'A'
668 >>> word
669 'HelpA'
670 >>> '<' + word*5 + '>'
671 '<HelpAHelpAHelpAHelpAHelpA>'
672 \end{verbatim}
673
674 Two string literals next to each other are automatically concatenated;
675 the first line above could also have been written \samp{word = 'Help'
676 'A'}; this only works with two literals, not with arbitrary string
677 expressions:
678
679 \begin{verbatim}
680 >>> 'str' 'ing'                   #  <-  This is ok
681 'string'
682 >>> 'str'.strip() + 'ing'   #  <-  This is ok
683 'string'
684 >>> 'str'.strip() 'ing'     #  <-  This is invalid
685   File "<stdin>", line 1, in ?
686     'str'.strip() 'ing'
687                       ^
688 SyntaxError: invalid syntax
689 \end{verbatim}
690
691 Strings can be subscripted (indexed); like in C, the first character
692 of a string has subscript (index) 0.  There is no separate character
693 type; a character is simply a string of size one.  Like in Icon,
694 substrings can be specified with the \emph{slice notation}: two indices
695 separated by a colon.
696
697 \begin{verbatim}
698 >>> word[4]
699 'A'
700 >>> word[0:2]
701 'He'
702 >>> word[2:4]
703 'lp'
704 \end{verbatim}
705
706 Slice indices have useful defaults; an omitted first index defaults to
707 zero, an omitted second index defaults to the size of the string being
708 sliced.
709
710 \begin{verbatim}
711 >>> word[:2]    # The first two characters
712 'He'
713 >>> word[2:]    # Everything except the first two characters
714 'lpA'
715 \end{verbatim}
716
717 Unlike a C string, Python strings cannot be changed.  Assigning to an 
718 indexed position in the string results in an error:
719
720 \begin{verbatim}
721 >>> word[0] = 'x'
722 Traceback (most recent call last):
723   File "<stdin>", line 1, in ?
724 TypeError: object doesn't support item assignment
725 >>> word[:1] = 'Splat'
726 Traceback (most recent call last):
727   File "<stdin>", line 1, in ?
728 TypeError: object doesn't support slice assignment
729 \end{verbatim}
730
731 However, creating a new string with the combined content is easy and
732 efficient:
733
734 \begin{verbatim}
735 >>> 'x' + word[1:]
736 'xelpA'
737 >>> 'Splat' + word[4]
738 'SplatA'
739 \end{verbatim}
740
741 Here's a useful invariant of slice operations:
742 \code{s[:i] + s[i:]} equals \code{s}.
743
744 \begin{verbatim}
745 >>> word[:2] + word[2:]
746 'HelpA'
747 >>> word[:3] + word[3:]
748 'HelpA'
749 \end{verbatim}
750
751 Degenerate slice indices are handled gracefully: an index that is too
752 large is replaced by the string size, an upper bound smaller than the
753 lower bound returns an empty string.
754
755 \begin{verbatim}
756 >>> word[1:100]
757 'elpA'
758 >>> word[10:]
759 ''
760 >>> word[2:1]
761 ''
762 \end{verbatim}
763
764 Indices may be negative numbers, to start counting from the right.
765 For example:
766
767 \begin{verbatim}
768 >>> word[-1]     # The last character
769 'A'
770 >>> word[-2]     # The last-but-one character
771 'p'
772 >>> word[-2:]    # The last two characters
773 'pA'
774 >>> word[:-2]    # Everything except the last two characters
775 'Hel'
776 \end{verbatim}
777
778 But note that -0 is really the same as 0, so it does not count from
779 the right!
780
781 \begin{verbatim}
782 >>> word[-0]     # (since -0 equals 0)
783 'H'
784 \end{verbatim}
785
786 Out-of-range negative slice indices are truncated, but don't try this
787 for single-element (non-slice) indices:
788
789 \begin{verbatim}
790 >>> word[-100:]
791 'HelpA'
792 >>> word[-10]    # error
793 Traceback (most recent call last):
794   File "<stdin>", line 1, in ?
795 IndexError: string index out of range
796 \end{verbatim}
797
798 The best way to remember how slices work is to think of the indices as
799 pointing \emph{between} characters, with the left edge of the first
800 character numbered 0.  Then the right edge of the last character of a
801 string of \var{n} characters has index \var{n}, for example:
802
803 \begin{verbatim}
804  +---+---+---+---+---+ 
805  | H | e | l | p | A |
806  +---+---+---+---+---+ 
807  0   1   2   3   4   5 
808 -5  -4  -3  -2  -1
809 \end{verbatim}
810
811 The first row of numbers gives the position of the indices 0...5 in
812 the string; the second row gives the corresponding negative indices.
813 The slice from \var{i} to \var{j} consists of all characters between
814 the edges labeled \var{i} and \var{j}, respectively.
815
816 For non-negative indices, the length of a slice is the difference of
817 the indices, if both are within bounds.  For example, the length of
818 \code{word[1:3]} is 2.
819
820 The built-in function \function{len()} returns the length of a string:
821
822 \begin{verbatim}
823 >>> s = 'supercalifragilisticexpialidocious'
824 >>> len(s)
825 34
826 \end{verbatim}
827
828
829 \begin{seealso}
830   \seetitle[../lib/typesseq.html]{Sequence Types}%
831            {Strings, and the Unicode strings described in the next
832             section, are examples of \emph{sequence types}, and
833             support the common operations supported by such types.}
834   \seetitle[../lib/string-methods.html]{String Methods}%
835            {Both strings and Unicode strings support a large number of
836             methods for basic transformations and searching.}
837   \seetitle[../lib/typesseq-strings.html]{String Formatting Operations}%
838            {The formatting operations invoked when strings and Unicode
839             strings are the left operand of the \code{\%} operator are
840             described in more detail here.}
841 \end{seealso}
842
843
844 \subsection{Unicode Strings \label{unicodeStrings}}
845 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
846
847 Starting with Python 2.0 a new data type for storing text data is
848 available to the programmer: the Unicode object. It can be used to
849 store and manipulate Unicode data (see \url{http://www.unicode.org/})
850 and integrates well with the existing string objects, providing
851 auto-conversions where necessary.
852
853 Unicode has the advantage of providing one ordinal for every character
854 in every script used in modern and ancient texts. Previously, there
855 were only 256 possible ordinals for script characters and texts were
856 typically bound to a code page which mapped the ordinals to script
857 characters. This lead to very much confusion especially with respect
858 to internationalization (usually written as \samp{i18n} ---
859 \character{i} + 18 characters + \character{n}) of software.  Unicode
860 solves these problems by defining one code page for all scripts.
861
862 Creating Unicode strings in Python is just as simple as creating
863 normal strings:
864
865 \begin{verbatim}
866 >>> u'Hello World !'
867 u'Hello World !'
868 \end{verbatim}
869
870 The small \character{u} in front of the quote indicates that an
871 Unicode string is supposed to be created. If you want to include
872 special characters in the string, you can do so by using the Python
873 \emph{Unicode-Escape} encoding. The following example shows how:
874
875 \begin{verbatim}
876 >>> u'Hello\u0020World !'
877 u'Hello World !'
878 \end{verbatim}
879
880 The escape sequence \code{\e u0020} indicates to insert the Unicode
881 character with the ordinal value 0x0020 (the space character) at the
882 given position.
883
884 Other characters are interpreted by using their respective ordinal
885 values directly as Unicode ordinals.  If you have literal strings
886 in the standard Latin-1 encoding that is used in many Western countries,
887 you will find it convenient that the lower 256 characters
888 of Unicode are the same as the 256 characters of Latin-1.
889
890 For experts, there is also a raw mode just like the one for normal
891 strings. You have to prefix the opening quote with 'ur' to have
892 Python use the \emph{Raw-Unicode-Escape} encoding. It will only apply
893 the above \code{\e uXXXX} conversion if there is an uneven number of
894 backslashes in front of the small 'u'.
895
896 \begin{verbatim}
897 >>> ur'Hello\u0020World !'
898 u'Hello World !'
899 >>> ur'Hello\\u0020World !'
900 u'Hello\\\\u0020World !'
901 \end{verbatim}
902
903 The raw mode is most useful when you have to enter lots of
904 backslashes, as can be necessary in regular expressions.
905
906 Apart from these standard encodings, Python provides a whole set of
907 other ways of creating Unicode strings on the basis of a known
908 encoding. 
909
910 The built-in function \function{unicode()}\bifuncindex{unicode} provides
911 access to all registered Unicode codecs (COders and DECoders). Some of
912 the more well known encodings which these codecs can convert are
913 \emph{Latin-1}, \emph{ASCII}, \emph{UTF-8}, and \emph{UTF-16}.
914 The latter two are variable-length encodings that store each Unicode
915 character in one or more bytes. The default encoding is
916 normally set to \ASCII, which passes through characters in the range
917 0 to 127 and rejects any other characters with an error.
918 When a Unicode string is printed, written to a file, or converted
919 with \function{str()}, conversion takes place using this default encoding.
920
921 \begin{verbatim}
922 >>> u"abc"
923 u'abc'
924 >>> str(u"abc")
925 'abc'
926 >>> u"äöü"
927 u'\xe4\xf6\xfc'
928 >>> str(u"äöü")
929 Traceback (most recent call last):
930   File "<stdin>", line 1, in ?
931 UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128)
932 \end{verbatim}
933
934 To convert a Unicode string into an 8-bit string using a specific
935 encoding, Unicode objects provide an \function{encode()} method
936 that takes one argument, the name of the encoding.  Lowercase names
937 for encodings are preferred.
938
939 \begin{verbatim}
940 >>> u"äöü".encode('utf-8')
941 '\xc3\xa4\xc3\xb6\xc3\xbc'
942 \end{verbatim}
943
944 If you have data in a specific encoding and want to produce a
945 corresponding Unicode string from it, you can use the
946 \function{unicode()} function with the encoding name as the second
947 argument.
948
949 \begin{verbatim}
950 >>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8')
951 u'\xe4\xf6\xfc'
952 \end{verbatim}
953
954 \subsection{Lists \label{lists}}
955
956 Python knows a number of \emph{compound} data types, used to group
957 together other values.  The most versatile is the \emph{list}, which
958 can be written as a list of comma-separated values (items) between
959 square brackets.  List items need not all have the same type.
960
961 \begin{verbatim}
962 >>> a = ['spam', 'eggs', 100, 1234]
963 >>> a
964 ['spam', 'eggs', 100, 1234]
965 \end{verbatim}
966
967 Like string indices, list indices start at 0, and lists can be sliced,
968 concatenated and so on:
969
970 \begin{verbatim}
971 >>> a[0]
972 'spam'
973 >>> a[3]
974 1234
975 >>> a[-2]
976 100
977 >>> a[1:-1]
978 ['eggs', 100]
979 >>> a[:2] + ['bacon', 2*2]
980 ['spam', 'eggs', 'bacon', 4]
981 >>> 3*a[:3] + ['Boo!']
982 ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boo!']
983 \end{verbatim}
984
985 Unlike strings, which are \emph{immutable}, it is possible to change
986 individual elements of a list:
987
988 \begin{verbatim}
989 >>> a
990 ['spam', 'eggs', 100, 1234]
991 >>> a[2] = a[2] + 23
992 >>> a
993 ['spam', 'eggs', 123, 1234]
994 \end{verbatim}
995
996 Assignment to slices is also possible, and this can even change the size
997 of the list:
998
999 \begin{verbatim}
1000 >>> # Replace some items:
1001 ... a[0:2] = [1, 12]
1002 >>> a
1003 [1, 12, 123, 1234]
1004 >>> # Remove some:
1005 ... a[0:2] = []
1006 >>> a
1007 [123, 1234]
1008 >>> # Insert some:
1009 ... a[1:1] = ['bletch', 'xyzzy']
1010 >>> a
1011 [123, 'bletch', 'xyzzy', 1234]
1012 >>> a[:0] = a     # Insert (a copy of) itself at the beginning
1013 >>> a
1014 [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
1015 \end{verbatim}
1016
1017 The built-in function \function{len()} also applies to lists:
1018
1019 \begin{verbatim}
1020 >>> len(a)
1021 8
1022 \end{verbatim}
1023
1024 It is possible to nest lists (create lists containing other lists),
1025 for example:
1026
1027 \begin{verbatim}
1028 >>> q = [2, 3]
1029 >>> p = [1, q, 4]
1030 >>> len(p)
1031 3
1032 >>> p[1]
1033 [2, 3]
1034 >>> p[1][0]
1035 2
1036 >>> p[1].append('xtra')     # See section 5.1
1037 >>> p
1038 [1, [2, 3, 'xtra'], 4]
1039 >>> q
1040 [2, 3, 'xtra']
1041 \end{verbatim}
1042
1043 Note that in the last example, \code{p[1]} and \code{q} really refer to
1044 the same object!  We'll come back to \emph{object semantics} later.
1045
1046 \section{First Steps Towards Programming \label{firstSteps}}
1047
1048 Of course, we can use Python for more complicated tasks than adding
1049 two and two together.  For instance, we can write an initial
1050 sub-sequence of the \emph{Fibonacci} series as follows:
1051
1052 \begin{verbatim}
1053 >>> # Fibonacci series:
1054 ... # the sum of two elements defines the next
1055 ... a, b = 0, 1
1056 >>> while b < 10:
1057 ...       print b
1058 ...       a, b = b, a+b
1059 ... 
1060 1
1061 1
1062 2
1063 3
1064 5
1065 8
1066 \end{verbatim}
1067
1068 This example introduces several new features.
1069
1070 \begin{itemize}
1071
1072 \item
1073 The first line contains a \emph{multiple assignment}: the variables
1074 \code{a} and \code{b} simultaneously get the new values 0 and 1.  On the
1075 last line this is used again, demonstrating that the expressions on
1076 the right-hand side are all evaluated first before any of the
1077 assignments take place.  The right-hand side expressions are evaluated 
1078 from the left to the right.
1079
1080 \item
1081 The \keyword{while} loop executes as long as the condition (here:
1082 \code{b < 10}) remains true.  In Python, like in C, any non-zero
1083 integer value is true; zero is false.  The condition may also be a
1084 string or list value, in fact any sequence; anything with a non-zero
1085 length is true, empty sequences are false.  The test used in the
1086 example is a simple comparison.  The standard comparison operators are
1087 written the same as in C: \code{<} (less than), \code{>} (greater than),
1088 \code{==} (equal to), \code{<=} (less than or equal to),
1089 \code{>=} (greater than or equal to) and \code{!=} (not equal to).
1090
1091 \item
1092 The \emph{body} of the loop is \emph{indented}: indentation is Python's
1093 way of grouping statements.  Python does not (yet!) provide an
1094 intelligent input line editing facility, so you have to type a tab or
1095 space(s) for each indented line.  In practice you will prepare more
1096 complicated input for Python with a text editor; most text editors have
1097 an auto-indent facility.  When a compound statement is entered
1098 interactively, it must be followed by a blank line to indicate
1099 completion (since the parser cannot guess when you have typed the last
1100 line).  Note that each line within a basic block must be indented by
1101 the same amount.
1102
1103 \item
1104 The \keyword{print} statement writes the value of the expression(s) it is
1105 given.  It differs from just writing the expression you want to write
1106 (as we did earlier in the calculator examples) in the way it handles
1107 multiple expressions and strings.  Strings are printed without quotes,
1108 and a space is inserted between items, so you can format things nicely,
1109 like this:
1110
1111 \begin{verbatim}
1112 >>> i = 256*256
1113 >>> print 'The value of i is', i
1114 The value of i is 65536
1115 \end{verbatim}
1116
1117 A trailing comma avoids the newline after the output:
1118
1119 \begin{verbatim}
1120 >>> a, b = 0, 1
1121 >>> while b < 1000:
1122 ...     print b,
1123 ...     a, b = b, a+b
1124 ... 
1125 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
1126 \end{verbatim}
1127
1128 Note that the interpreter inserts a newline before it prints the next
1129 prompt if the last line was not completed.
1130
1131 \end{itemize}
1132
1133
1134 \chapter{More Control Flow Tools \label{moreControl}}
1135
1136 Besides the \keyword{while} statement just introduced, Python knows
1137 the usual control flow statements known from other languages, with
1138 some twists.
1139
1140 \section{\keyword{if} Statements \label{if}}
1141
1142 Perhaps the most well-known statement type is the
1143 \keyword{if} statement.  For example:
1144
1145 \begin{verbatim}
1146 >>> x = int(raw_input("Please enter an integer: "))
1147 >>> if x < 0:
1148 ...      x = 0
1149 ...      print 'Negative changed to zero'
1150 ... elif x == 0:
1151 ...      print 'Zero'
1152 ... elif x == 1:
1153 ...      print 'Single'
1154 ... else:
1155 ...      print 'More'
1156 ... 
1157 \end{verbatim}
1158
1159 There can be zero or more \keyword{elif} parts, and the
1160 \keyword{else} part is optional.  The keyword `\keyword{elif}' is
1161 short for `else if', and is useful to avoid excessive indentation.  An 
1162 \keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence
1163 %    Weird spacings happen here if the wrapping of the source text
1164 %    gets changed in the wrong way.
1165 is a substitute for the \keyword{switch} or
1166 \keyword{case} statements found in other languages.
1167
1168
1169 \section{\keyword{for} Statements \label{for}}
1170
1171 The \keyword{for}\stindex{for} statement in Python differs a bit from
1172 what you may be used to in C or Pascal.  Rather than always
1173 iterating over an arithmetic progression of numbers (like in Pascal),
1174 or giving the user the ability to define both the iteration step and
1175 halting condition (as C), Python's
1176 \keyword{for}\stindex{for} statement iterates over the items of any
1177 sequence (a list or a string), in the order that they appear in
1178 the sequence.  For example (no pun intended):
1179 % One suggestion was to give a real C example here, but that may only
1180 % serve to confuse non-C programmers.
1181
1182 \begin{verbatim}
1183 >>> # Measure some strings:
1184 ... a = ['cat', 'window', 'defenestrate']
1185 >>> for x in a:
1186 ...     print x, len(x)
1187 ... 
1188 cat 3
1189 window 6
1190 defenestrate 12
1191 \end{verbatim}
1192
1193 It is not safe to modify the sequence being iterated over in the loop
1194 (this can only happen for mutable sequence types, such as lists).  If
1195 you need to modify the list you are iterating over (for example, to
1196 duplicate selected items) you must iterate over a copy.  The slice
1197 notation makes this particularly convenient:
1198
1199 \begin{verbatim}
1200 >>> for x in a[:]: # make a slice copy of the entire list
1201 ...    if len(x) > 6: a.insert(0, x)
1202 ... 
1203 >>> a
1204 ['defenestrate', 'cat', 'window', 'defenestrate']
1205 \end{verbatim}
1206
1207
1208 \section{The \function{range()} Function \label{range}}
1209
1210 If you do need to iterate over a sequence of numbers, the built-in
1211 function \function{range()} comes in handy.  It generates lists
1212 containing arithmetic progressions:
1213
1214 \begin{verbatim}
1215 >>> range(10)
1216 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1217 \end{verbatim}
1218
1219 The given end point is never part of the generated list;
1220 \code{range(10)} generates a list of 10 values, the legal
1221 indices for items of a sequence of length 10.  It is possible to let
1222 the range start at another number, or to specify a different increment
1223 (even negative; sometimes this is called the `step'):
1224
1225 \begin{verbatim}
1226 >>> range(5, 10)
1227 [5, 6, 7, 8, 9]
1228 >>> range(0, 10, 3)
1229 [0, 3, 6, 9]
1230 >>> range(-10, -100, -30)
1231 [-10, -40, -70]
1232 \end{verbatim}
1233
1234 To iterate over the indices of a sequence, combine
1235 \function{range()} and \function{len()} as follows:
1236
1237 \begin{verbatim}
1238 >>> a = ['Mary', 'had', 'a', 'little', 'lamb']
1239 >>> for i in range(len(a)):
1240 ...     print i, a[i]
1241 ... 
1242 0 Mary
1243 1 had
1244 2 a
1245 3 little
1246 4 lamb
1247 \end{verbatim}
1248
1249
1250 \section{\keyword{break} and \keyword{continue} Statements, and
1251          \keyword{else} Clauses on Loops
1252          \label{break}}
1253
1254 The \keyword{break} statement, like in C, breaks out of the smallest
1255 enclosing \keyword{for} or \keyword{while} loop.
1256
1257 The \keyword{continue} statement, also borrowed from C, continues
1258 with the next iteration of the loop.
1259
1260 Loop statements may have an \code{else} clause; it is executed when
1261 the loop terminates through exhaustion of the list (with
1262 \keyword{for}) or when the condition becomes false (with
1263 \keyword{while}), but not when the loop is terminated by a
1264 \keyword{break} statement.  This is exemplified by the following loop,
1265 which searches for prime numbers:
1266
1267 \begin{verbatim}
1268 >>> for n in range(2, 10):
1269 ...     for x in range(2, n):
1270 ...         if n % x == 0:
1271 ...             print n, 'equals', x, '*', n/x
1272 ...             break
1273 ...     else:
1274 ...         # loop fell through without finding a factor
1275 ...         print n, 'is a prime number'
1276 ... 
1277 2 is a prime number
1278 3 is a prime number
1279 4 equals 2 * 2
1280 5 is a prime number
1281 6 equals 2 * 3
1282 7 is a prime number
1283 8 equals 2 * 4
1284 9 equals 3 * 3
1285 \end{verbatim}
1286
1287
1288 \section{\keyword{pass} Statements \label{pass}}
1289
1290 The \keyword{pass} statement does nothing.
1291 It can be used when a statement is required syntactically but the
1292 program requires no action.
1293 For example:
1294
1295 \begin{verbatim}
1296 >>> while True:
1297 ...       pass # Busy-wait for keyboard interrupt
1298 ... 
1299 \end{verbatim}
1300
1301
1302 \section{Defining Functions \label{functions}}
1303
1304 We can create a function that writes the Fibonacci series to an
1305 arbitrary boundary:
1306
1307 \begin{verbatim}
1308 >>> def fib(n):    # write Fibonacci series up to n
1309 ...     """Print a Fibonacci series up to n."""
1310 ...     a, b = 0, 1
1311 ...     while b < n:
1312 ...         print b,
1313 ...         a, b = b, a+b
1314 ... 
1315 >>> # Now call the function we just defined:
1316 ... fib(2000)
1317 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
1318 \end{verbatim}
1319
1320 The keyword \keyword{def} introduces a function \emph{definition}.  It
1321 must be followed by the function name and the parenthesized list of
1322 formal parameters.  The statements that form the body of the function
1323 start at the next line, and must be indented.  The first statement of
1324 the function body can optionally be a string literal; this string
1325 literal is the function's \index{documentation strings}documentation
1326 string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation}
1327
1328 There are tools which use docstrings to automatically produce online
1329 or printed documentation, or to let the user interactively browse
1330 through code; it's good practice to include docstrings in code that
1331 you write, so try to make a habit of it.
1332
1333 The \emph{execution} of a function introduces a new symbol table used
1334 for the local variables of the function.  More precisely, all variable
1335 assignments in a function store the value in the local symbol table;
1336 whereas variable references first look in the local symbol table, then
1337 in the global symbol table, and then in the table of built-in names.
1338 Thus,  global variables cannot be directly assigned a value within a
1339 function (unless named in a \keyword{global} statement), although
1340 they may be referenced.
1341
1342 The actual parameters (arguments) to a function call are introduced in
1343 the local symbol table of the called function when it is called; thus,
1344 arguments are passed using \emph{call by value} (where the
1345 \emph{value} is always an object \emph{reference}, not the value of
1346 the object).\footnote{
1347          Actually, \emph{call by object reference} would be a better
1348          description, since if a mutable object is passed, the caller
1349          will see any changes the callee makes to it (items
1350          inserted into a list).
1351 } When a function calls another function, a new local symbol table is
1352 created for that call.
1353
1354 A function definition introduces the function name in the current
1355 symbol table.  The value of the function name
1356 has a type that is recognized by the interpreter as a user-defined
1357 function.  This value can be assigned to another name which can then
1358 also be used as a function.  This serves as a general renaming
1359 mechanism:
1360
1361 \begin{verbatim}
1362 >>> fib
1363 <function fib at 10042ed0>
1364 >>> f = fib
1365 >>> f(100)
1366 1 1 2 3 5 8 13 21 34 55 89
1367 \end{verbatim}
1368
1369 You might object that \code{fib} is not a function but a procedure.  In
1370 Python, like in C, procedures are just functions that don't return a
1371 value.  In fact, technically speaking, procedures do return a value,
1372 albeit a rather boring one.  This value is called \code{None} (it's a
1373 built-in name).  Writing the value \code{None} is normally suppressed by
1374 the interpreter if it would be the only value written.  You can see it
1375 if you really want to:
1376
1377 \begin{verbatim}
1378 >>> print fib(0)
1379 None
1380 \end{verbatim}
1381
1382 It is simple to write a function that returns a list of the numbers of
1383 the Fibonacci series, instead of printing it:
1384
1385 \begin{verbatim}
1386 >>> def fib2(n): # return Fibonacci series up to n
1387 ...     """Return a list containing the Fibonacci series up to n."""
1388 ...     result = []
1389 ...     a, b = 0, 1
1390 ...     while b < n:
1391 ...         result.append(b)    # see below
1392 ...         a, b = b, a+b
1393 ...     return result
1394 ... 
1395 >>> f100 = fib2(100)    # call it
1396 >>> f100                # write the result
1397 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
1398 \end{verbatim}
1399
1400 This example, as usual, demonstrates some new Python features:
1401
1402 \begin{itemize}
1403
1404 \item
1405 The \keyword{return} statement returns with a value from a function.
1406 \keyword{return} without an expression argument returns \code{None}.
1407 Falling off the end of a procedure also returns \code{None}.
1408
1409 \item
1410 The statement \code{result.append(b)} calls a \emph{method} of the list
1411 object \code{result}.  A method is a function that `belongs' to an
1412 object and is named \code{obj.methodname}, where \code{obj} is some
1413 object (this may be an expression), and \code{methodname} is the name
1414 of a method that is defined by the object's type.  Different types
1415 define different methods.  Methods of different types may have the
1416 same name without causing ambiguity.  (It is possible to define your
1417 own object types and methods, using \emph{classes}, as discussed later
1418 in this tutorial.)
1419 The method \method{append()} shown in the example is defined for
1420 list objects; it adds a new element at the end of the list.  In this
1421 example it is equivalent to \samp{result = result + [b]}, but more
1422 efficient.
1423
1424 \end{itemize}
1425
1426 \section{More on Defining Functions \label{defining}}
1427
1428 It is also possible to define functions with a variable number of
1429 arguments.  There are three forms, which can be combined.
1430
1431 \subsection{Default Argument Values \label{defaultArgs}}
1432
1433 The most useful form is to specify a default value for one or more
1434 arguments.  This creates a function that can be called with fewer
1435 arguments than it is defined to allow.  For example:
1436
1437 \begin{verbatim}
1438 def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
1439     while True:
1440         ok = raw_input(prompt)
1441         if ok in ('y', 'ye', 'yes'): return True
1442         if ok in ('n', 'no', 'nop', 'nope'): return False
1443         retries = retries - 1
1444         if retries < 0: raise IOError, 'refusenik user'
1445         print complaint
1446 \end{verbatim}
1447
1448 This function can be called either like this:
1449 \code{ask_ok('Do you really want to quit?')} or like this:
1450 \code{ask_ok('OK to overwrite the file?', 2)}.
1451
1452 This example also introduces the \keyword{in} keyword. This tests
1453 whether or not a sequence contains a certain value.
1454
1455 The default values are evaluated at the point of function definition
1456 in the \emph{defining} scope, so that
1457
1458 \begin{verbatim}
1459 i = 5
1460
1461 def f(arg=i):
1462     print arg
1463
1464 i = 6
1465 f()
1466 \end{verbatim}
1467
1468 will print \code{5}.
1469
1470 \strong{Important warning:}  The default value is evaluated only once.
1471 This makes a difference when the default is a mutable object such as a
1472 list, dictionary, or instances of most classes.  For example, the
1473 following function accumulates the arguments passed to it on
1474 subsequent calls:
1475
1476 \begin{verbatim}
1477 def f(a, L=[]):
1478     L.append(a)
1479     return L
1480
1481 print f(1)
1482 print f(2)
1483 print f(3)
1484 \end{verbatim}
1485
1486 This will print
1487
1488 \begin{verbatim}
1489 [1]
1490 [1, 2]
1491 [1, 2, 3]
1492 \end{verbatim}
1493
1494 If you don't want the default to be shared between subsequent calls,
1495 you can write the function like this instead:
1496
1497 \begin{verbatim}
1498 def f(a, L=None):
1499     if L is None:
1500         L = []
1501     L.append(a)
1502     return L
1503 \end{verbatim}
1504
1505 \subsection{Keyword Arguments \label{keywordArgs}}
1506
1507 Functions can also be called using
1508 keyword arguments of the form \samp{\var{keyword} = \var{value}}.  For
1509 instance, the following function:
1510
1511 \begin{verbatim}
1512 def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
1513     print "-- This parrot wouldn't", action,
1514     print "if you put", voltage, "volts through it."
1515     print "-- Lovely plumage, the", type
1516     print "-- It's", state, "!"
1517 \end{verbatim}
1518
1519 could be called in any of the following ways:
1520
1521 \begin{verbatim}
1522 parrot(1000)
1523 parrot(action = 'VOOOOOM', voltage = 1000000)
1524 parrot('a thousand', state = 'pushing up the daisies')
1525 parrot('a million', 'bereft of life', 'jump')
1526 \end{verbatim}
1527
1528 but the following calls would all be invalid:
1529
1530 \begin{verbatim}
1531 parrot()                     # required argument missing
1532 parrot(voltage=5.0, 'dead')  # non-keyword argument following keyword
1533 parrot(110, voltage=220)     # duplicate value for argument
1534 parrot(actor='John Cleese')  # unknown keyword
1535 \end{verbatim}
1536
1537 In general, an argument list must have any positional arguments
1538 followed by any keyword arguments, where the keywords must be chosen
1539 from the formal parameter names.  It's not important whether a formal
1540 parameter has a default value or not.  No argument may receive a
1541 value more than once --- formal parameter names corresponding to
1542 positional arguments cannot be used as keywords in the same calls.
1543 Here's an example that fails due to this restriction:
1544
1545 \begin{verbatim}
1546 >>> def function(a):
1547 ...     pass
1548 ... 
1549 >>> function(0, a=0)
1550 Traceback (most recent call last):
1551   File "<stdin>", line 1, in ?
1552 TypeError: function() got multiple values for keyword argument 'a'
1553 \end{verbatim}
1554
1555 When a final formal parameter of the form \code{**\var{name}} is
1556 present, it receives a \ulink{dictionary}{../lib/typesmapping.html}
1557 containing all keyword arguments except for those corresponding to
1558 a formal parameter.  This may be
1559 combined with a formal parameter of the form
1560 \code{*\var{name}} (described in the next subsection) which receives a
1561 tuple containing the positional arguments beyond the formal parameter
1562 list.  (\code{*\var{name}} must occur before \code{**\var{name}}.)
1563 For example, if we define a function like this:
1564
1565 \begin{verbatim}
1566 def cheeseshop(kind, *arguments, **keywords):
1567     print "-- Do you have any", kind, '?'
1568     print "-- I'm sorry, we're all out of", kind
1569     for arg in arguments: print arg
1570     print '-'*40
1571     keys = keywords.keys()
1572     keys.sort()
1573     for kw in keys: print kw, ':', keywords[kw]
1574 \end{verbatim}
1575
1576 It could be called like this:
1577
1578 \begin{verbatim}
1579 cheeseshop('Limburger', "It's very runny, sir.",
1580            "It's really very, VERY runny, sir.",
1581            client='John Cleese',
1582            shopkeeper='Michael Palin',
1583            sketch='Cheese Shop Sketch')
1584 \end{verbatim}
1585
1586 and of course it would print:
1587
1588 \begin{verbatim}
1589 -- Do you have any Limburger ?
1590 -- I'm sorry, we're all out of Limburger
1591 It's very runny, sir.
1592 It's really very, VERY runny, sir.
1593 ----------------------------------------
1594 client : John Cleese
1595 shopkeeper : Michael Palin
1596 sketch : Cheese Shop Sketch
1597 \end{verbatim}
1598
1599 Note that the \method{sort()} method of the list of keyword argument
1600 names is called before printing the contents of the \code{keywords}
1601 dictionary; if this is not done, the order in which the arguments are
1602 printed is undefined.
1603
1604
1605 \subsection{Arbitrary Argument Lists \label{arbitraryArgs}}
1606
1607 Finally, the least frequently used option is to specify that a
1608 function can be called with an arbitrary number of arguments.  These
1609 arguments will be wrapped up in a tuple.  Before the variable number
1610 of arguments, zero or more normal arguments may occur.
1611
1612 \begin{verbatim}
1613 def fprintf(file, format, *args):
1614     file.write(format % args)
1615 \end{verbatim}
1616
1617
1618 \subsection{Unpacking Argument Lists \label{unpacking-arguments}}
1619
1620 The reverse situation occurs when the arguments are already in a list
1621 or tuple but need to be unpacked for a function call requiring separate
1622 positional arguments.  For instance, the built-in \function{range()}
1623 function expects separate \var{start} and \var{stop} arguments.  If they
1624 are not available separately, write the function call with the 
1625 \code{*}-operator to unpack the arguments out of a list or tuple:
1626
1627 \begin{verbatim}
1628 >>> range(3, 6)             # normal call with separate arguments
1629 [3, 4, 5]
1630 >>> args = [3, 6]
1631 >>> range(*args)            # call with arguments unpacked from a list
1632 [3, 4, 5]
1633 \end{verbatim}
1634
1635 In the same fashion, dictionaries can deliver keyword arguments with the
1636 \code{**}-operator:
1637
1638 \begin{verbatim}
1639 >>> def parrot(voltage, state='a stiff', action='voom'):
1640 ...     print "-- This parrot wouldn't", action,
1641 ...     print "if you put", voltage, "volts through it.",
1642 ...     print "E's", state, "!"
1643 ...
1644 >>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
1645 >>> parrot(**d)
1646 -- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
1647 \end{verbatim}
1648
1649
1650 \subsection{Lambda Forms \label{lambda}}
1651
1652 By popular demand, a few features commonly found in functional
1653 programming languages like Lisp have been added to Python.  With the
1654 \keyword{lambda} keyword, small anonymous functions can be created.
1655 Here's a function that returns the sum of its two arguments:
1656 \samp{lambda a, b: a+b}.  Lambda forms can be used wherever function
1657 objects are required.  They are syntactically restricted to a single
1658 expression.  Semantically, they are just syntactic sugar for a normal
1659 function definition.  Like nested function definitions, lambda forms
1660 can reference variables from the containing scope:
1661
1662 \begin{verbatim}
1663 >>> def make_incrementor(n):
1664 ...     return lambda x: x + n
1665 ...
1666 >>> f = make_incrementor(42)
1667 >>> f(0)
1668 42
1669 >>> f(1)
1670 43
1671 \end{verbatim}
1672
1673
1674 \subsection{Documentation Strings \label{docstrings}}
1675
1676 There are emerging conventions about the content and formatting of
1677 documentation strings.
1678 \index{docstrings}\index{documentation strings}
1679 \index{strings, documentation}
1680
1681 The first line should always be a short, concise summary of the
1682 object's purpose.  For brevity, it should not explicitly state the
1683 object's name or type, since these are available by other means
1684 (except if the name happens to be a verb describing a function's
1685 operation).  This line should begin with a capital letter and end with
1686 a period.
1687
1688 If there are more lines in the documentation string, the second line
1689 should be blank, visually separating the summary from the rest of the
1690 description.  The following lines should be one or more paragraphs
1691 describing the object's calling conventions, its side effects, etc.
1692
1693 The Python parser does not strip indentation from multi-line string
1694 literals in Python, so tools that process documentation have to strip
1695 indentation if desired.  This is done using the following convention.
1696 The first non-blank line \emph{after} the first line of the string
1697 determines the amount of indentation for the entire documentation
1698 string.  (We can't use the first line since it is generally adjacent
1699 to the string's opening quotes so its indentation is not apparent in
1700 the string literal.)  Whitespace ``equivalent'' to this indentation is
1701 then stripped from the start of all lines of the string.  Lines that
1702 are indented less should not occur, but if they occur all their
1703 leading whitespace should be stripped.  Equivalence of whitespace
1704 should be tested after expansion of tabs (to 8 spaces, normally).
1705
1706 Here is an example of a multi-line docstring:
1707
1708 \begin{verbatim}
1709 >>> def my_function():
1710 ...     """Do nothing, but document it.
1711 ... 
1712 ...     No, really, it doesn't do anything.
1713 ...     """
1714 ...     pass
1715 ... 
1716 >>> print my_function.__doc__
1717 Do nothing, but document it.
1718
1719     No, really, it doesn't do anything.
1720     
1721 \end{verbatim}
1722
1723
1724
1725 \chapter{Data Structures \label{structures}}
1726
1727 This chapter describes some things you've learned about already in
1728 more detail, and adds some new things as well.
1729
1730
1731 \section{More on Lists \label{moreLists}}
1732
1733 The list data type has some more methods.  Here are all of the methods
1734 of list objects:
1735
1736 \begin{methoddesc}[list]{append}{x}
1737 Add an item to the end of the list;
1738 equivalent to \code{a[len(a):] = [\var{x}]}.
1739 \end{methoddesc}
1740
1741 \begin{methoddesc}[list]{extend}{L}
1742 Extend the list by appending all the items in the given list;
1743 equivalent to \code{a[len(a):] = \var{L}}.
1744 \end{methoddesc}
1745
1746 \begin{methoddesc}[list]{insert}{i, x}
1747 Insert an item at a given position.  The first argument is the index
1748 of the element before which to insert, so \code{a.insert(0, \var{x})}
1749 inserts at the front of the list, and \code{a.insert(len(a), \var{x})}
1750 is equivalent to \code{a.append(\var{x})}.
1751 \end{methoddesc}
1752
1753 \begin{methoddesc}[list]{remove}{x}
1754 Remove the first item from the list whose value is \var{x}.
1755 It is an error if there is no such item.
1756 \end{methoddesc}
1757
1758 \begin{methoddesc}[list]{pop}{\optional{i}}
1759 Remove the item at the given position in the list, and return it.  If
1760 no index is specified, \code{a.pop()} removes and returns the last item
1761 in the list.  The item is also removed from the list.  (The square brackets
1762 around the \var{i} in the method signature denote that the parameter
1763 is optional, not that you should type square brackets at that
1764 position.  You will see this notation frequently in the
1765 \citetitle[../lib/lib.html]{Python Library Reference}.)
1766 \end{methoddesc}
1767
1768 \begin{methoddesc}[list]{index}{x}
1769 Return the index in the list of the first item whose value is \var{x}.
1770 It is an error if there is no such item.
1771 \end{methoddesc}
1772
1773 \begin{methoddesc}[list]{count}{x}
1774 Return the number of times \var{x} appears in the list.
1775 \end{methoddesc}
1776
1777 \begin{methoddesc}[list]{sort}{}
1778 Sort the items of the list, in place.
1779 \end{methoddesc}
1780
1781 \begin{methoddesc}[list]{reverse}{}
1782 Reverse the elements of the list, in place.
1783 \end{methoddesc}
1784
1785 An example that uses most of the list methods:
1786
1787 \begin{verbatim}
1788 >>> a = [66.25, 333, 333, 1, 1234.5]
1789 >>> print a.count(333), a.count(66.25), a.count('x')
1790 2 1 0
1791 >>> a.insert(2, -1)
1792 >>> a.append(333)
1793 >>> a
1794 [66.25, 333, -1, 333, 1, 1234.5, 333]
1795 >>> a.index(333)
1796 1
1797 >>> a.remove(333)
1798 >>> a
1799 [66.25, -1, 333, 1, 1234.5, 333]
1800 >>> a.reverse()
1801 >>> a
1802 [333, 1234.5, 1, 333, -1, 66.25]
1803 >>> a.sort()
1804 >>> a
1805 [-1, 1, 66.25, 333, 333, 1234.5]
1806 \end{verbatim}
1807
1808
1809 \subsection{Using Lists as Stacks \label{lists-as-stacks}}
1810 \sectionauthor{Ka-Ping Yee}{ping@lfw.org}
1811
1812 The list methods make it very easy to use a list as a stack, where the
1813 last element added is the first element retrieved (``last-in,
1814 first-out'').  To add an item to the top of the stack, use
1815 \method{append()}.  To retrieve an item from the top of the stack, use
1816 \method{pop()} without an explicit index.  For example:
1817
1818 \begin{verbatim}
1819 >>> stack = [3, 4, 5]
1820 >>> stack.append(6)
1821 >>> stack.append(7)
1822 >>> stack
1823 [3, 4, 5, 6, 7]
1824 >>> stack.pop()
1825 7
1826 >>> stack
1827 [3, 4, 5, 6]
1828 >>> stack.pop()
1829 6
1830 >>> stack.pop()
1831 5
1832 >>> stack
1833 [3, 4]
1834 \end{verbatim}
1835
1836
1837 \subsection{Using Lists as Queues \label{lists-as-queues}}
1838 \sectionauthor{Ka-Ping Yee}{ping@lfw.org}
1839
1840 You can also use a list conveniently as a queue, where the first
1841 element added is the first element retrieved (``first-in,
1842 first-out'').  To add an item to the back of the queue, use
1843 \method{append()}.  To retrieve an item from the front of the queue,
1844 use \method{pop()} with \code{0} as the index.  For example:
1845
1846 \begin{verbatim}
1847 >>> queue = ["Eric", "John", "Michael"]
1848 >>> queue.append("Terry")           # Terry arrives
1849 >>> queue.append("Graham")          # Graham arrives
1850 >>> queue.pop(0)
1851 'Eric'
1852 >>> queue.pop(0)
1853 'John'
1854 >>> queue
1855 ['Michael', 'Terry', 'Graham']
1856 \end{verbatim}
1857
1858
1859 \subsection{Functional Programming Tools \label{functional}}
1860
1861 There are three built-in functions that are very useful when used with
1862 lists: \function{filter()}, \function{map()}, and \function{reduce()}.
1863
1864 \samp{filter(\var{function}, \var{sequence})} returns a sequence
1865 consisting of those items from the
1866 sequence for which \code{\var{function}(\var{item})} is true.
1867 If \var{sequence} is a \class{string} or \class{tuple}, the result will
1868 be of the same type; otherwise, it is always a \class{list}.
1869 For example, to compute some primes:
1870
1871 \begin{verbatim}
1872 >>> def f(x): return x % 2 != 0 and x % 3 != 0
1873 ...
1874 >>> filter(f, range(2, 25))
1875 [5, 7, 11, 13, 17, 19, 23]
1876 \end{verbatim}
1877
1878 \samp{map(\var{function}, \var{sequence})} calls
1879 \code{\var{function}(\var{item})} for each of the sequence's items and
1880 returns a list of the return values.  For example, to compute some
1881 cubes:
1882
1883 \begin{verbatim}
1884 >>> def cube(x): return x*x*x
1885 ...
1886 >>> map(cube, range(1, 11))
1887 [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
1888 \end{verbatim}
1889
1890 More than one sequence may be passed; the function must then have as
1891 many arguments as there are sequences and is called with the
1892 corresponding item from each sequence (or \code{None} if some sequence
1893 is shorter than another).  For example:
1894
1895 \begin{verbatim}
1896 >>> seq = range(8)
1897 >>> def add(x, y): return x+y
1898 ...
1899 >>> map(add, seq, seq)
1900 [0, 2, 4, 6, 8, 10, 12, 14]
1901 \end{verbatim}
1902
1903 \samp{reduce(\var{function}, \var{sequence})} returns a single value
1904 constructed by calling the binary function \var{function} on the first two
1905 items of the sequence, then on the result and the next item, and so
1906 on.  For example, to compute the sum of the numbers 1 through 10:
1907
1908 \begin{verbatim}
1909 >>> def add(x,y): return x+y
1910 ...
1911 >>> reduce(add, range(1, 11))
1912 55
1913 \end{verbatim}
1914
1915 If there's only one item in the sequence, its value is returned; if
1916 the sequence is empty, an exception is raised.
1917
1918 A third argument can be passed to indicate the starting value.  In this
1919 case the starting value is returned for an empty sequence, and the
1920 function is first applied to the starting value and the first sequence
1921 item, then to the result and the next item, and so on.  For example,
1922
1923 \begin{verbatim}
1924 >>> def sum(seq):
1925 ...     def add(x,y): return x+y
1926 ...     return reduce(add, seq, 0)
1927 ... 
1928 >>> sum(range(1, 11))
1929 55
1930 >>> sum([])
1931 0
1932 \end{verbatim}
1933
1934 Don't use this example's definition of \function{sum()}: since summing
1935 numbers is such a common need, a built-in function
1936 \code{sum(\var{sequence})} is already provided, and works exactly like
1937 this.
1938 \versionadded{2.3}
1939
1940 \subsection{List Comprehensions}
1941
1942 List comprehensions provide a concise way to create lists without resorting
1943 to use of \function{map()}, \function{filter()} and/or \keyword{lambda}.
1944 The resulting list definition tends often to be clearer than lists built
1945 using those constructs.  Each list comprehension consists of an expression
1946 followed by a \keyword{for} clause, then zero or more \keyword{for} or
1947 \keyword{if} clauses.  The result will be a list resulting from evaluating
1948 the expression in the context of the \keyword{for} and \keyword{if} clauses
1949 which follow it.  If the expression would evaluate to a tuple, it must be
1950 parenthesized.
1951
1952 \begin{verbatim}
1953 >>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
1954 >>> [weapon.strip() for weapon in freshfruit]
1955 ['banana', 'loganberry', 'passion fruit']
1956 >>> vec = [2, 4, 6]
1957 >>> [3*x for x in vec]
1958 [6, 12, 18]
1959 >>> [3*x for x in vec if x > 3]
1960 [12, 18]
1961 >>> [3*x for x in vec if x < 2]
1962 []
1963 >>> [[x,x**2] for x in vec]
1964 [[2, 4], [4, 16], [6, 36]]
1965 >>> [x, x**2 for x in vec]      # error - parens required for tuples
1966   File "<stdin>", line 1, in ?
1967     [x, x**2 for x in vec]
1968                ^
1969 SyntaxError: invalid syntax
1970 >>> [(x, x**2) for x in vec]
1971 [(2, 4), (4, 16), (6, 36)]
1972 >>> vec1 = [2, 4, 6]
1973 >>> vec2 = [4, 3, -9]
1974 >>> [x*y for x in vec1 for y in vec2]
1975 [8, 6, -18, 16, 12, -36, 24, 18, -54]
1976 >>> [x+y for x in vec1 for y in vec2]
1977 [6, 5, -7, 8, 7, -5, 10, 9, -3]
1978 >>> [vec1[i]*vec2[i] for i in range(len(vec1))]
1979 [8, 12, -54]
1980 \end{verbatim}
1981
1982 List comprehensions are much more flexible than \function{map()} and can be
1983 applied to complex expressions and nested functions:
1984
1985 \begin{verbatim}
1986 >>> [str(round(355/113.0, i)) for i in range(1,6)]
1987 ['3.1', '3.14', '3.142', '3.1416', '3.14159']
1988 \end{verbatim}
1989
1990
1991 \section{The \keyword{del} statement \label{del}}
1992
1993 There is a way to remove an item from a list given its index instead
1994 of its value: the \keyword{del} statement.  Unlike the \method{pop()})
1995 method which returns a value, the \keyword{del} keyword is a statement 
1996 and can also be used to
1997 remove slices from a list (which we did earlier by assignment of an
1998 empty list to the slice).  For example:
1999
2000 \begin{verbatim}
2001 >>> a = [-1, 1, 66.25, 333, 333, 1234.5]
2002 >>> del a[0]
2003 >>> a
2004 [1, 66.25, 333, 333, 1234.5]
2005 >>> del a[2:4]
2006 >>> a
2007 [1, 66.25, 1234.5]
2008 \end{verbatim}
2009
2010 \keyword{del} can also be used to delete entire variables:
2011
2012 \begin{verbatim}
2013 >>> del a
2014 \end{verbatim}
2015
2016 Referencing the name \code{a} hereafter is an error (at least until
2017 another value is assigned to it).  We'll find other uses for
2018 \keyword{del} later.
2019
2020
2021 \section{Tuples and Sequences \label{tuples}}
2022
2023 We saw that lists and strings have many common properties, such as
2024 indexing and slicing operations.  They are two examples of
2025 \ulink{\emph{sequence} data types}{../lib/typesseq.html}.  Since
2026 Python is an evolving language, other sequence data types may be
2027 added.  There is also another standard sequence data type: the
2028 \emph{tuple}.
2029
2030 A tuple consists of a number of values separated by commas, for
2031 instance:
2032
2033 \begin{verbatim}
2034 >>> t = 12345, 54321, 'hello!'
2035 >>> t[0]
2036 12345
2037 >>> t
2038 (12345, 54321, 'hello!')
2039 >>> # Tuples may be nested:
2040 ... u = t, (1, 2, 3, 4, 5)
2041 >>> u
2042 ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
2043 \end{verbatim}
2044
2045 As you see, on output tuples are always enclosed in parentheses, so
2046 that nested tuples are interpreted correctly; they may be input with
2047 or without surrounding parentheses, although often parentheses are
2048 necessary anyway (if the tuple is part of a larger expression).
2049
2050 Tuples have many uses.  For example: (x, y) coordinate pairs, employee
2051 records from a database, etc.  Tuples, like strings, are immutable: it
2052 is not possible to assign to the individual items of a tuple (you can
2053 simulate much of the same effect with slicing and concatenation,
2054 though).  It is also possible to create tuples which contain mutable
2055 objects, such as lists.
2056
2057 A special problem is the construction of tuples containing 0 or 1
2058 items: the syntax has some extra quirks to accommodate these.  Empty
2059 tuples are constructed by an empty pair of parentheses; a tuple with
2060 one item is constructed by following a value with a comma
2061 (it is not sufficient to enclose a single value in parentheses).
2062 Ugly, but effective.  For example:
2063
2064 \begin{verbatim}
2065 >>> empty = ()
2066 >>> singleton = 'hello',    # <-- note trailing comma
2067 >>> len(empty)
2068 0
2069 >>> len(singleton)
2070 1
2071 >>> singleton
2072 ('hello',)
2073 \end{verbatim}
2074
2075 The statement \code{t = 12345, 54321, 'hello!'} is an example of
2076 \emph{tuple packing}: the values \code{12345}, \code{54321} and
2077 \code{'hello!'} are packed together in a tuple.  The reverse operation
2078 is also possible:
2079
2080 \begin{verbatim}
2081 >>> x, y, z = t
2082 \end{verbatim}
2083
2084 This is called, appropriately enough, \emph{sequence unpacking}.
2085 Sequence unpacking requires the list of variables on the left to
2086 have the same number of elements as the length of the sequence.  Note
2087 that multiple assignment is really just a combination of tuple packing
2088 and sequence unpacking!
2089
2090 There is a small bit of asymmetry here:  packing multiple values
2091 always creates a tuple, and unpacking works for any sequence.
2092
2093 % XXX Add a bit on the difference between tuples and lists.
2094
2095
2096 \section{Sets \label{sets}}
2097
2098 Python also includes a data type for \emph{sets}.  A set is an unordered
2099 collection with no duplicate elements.  Basic uses include membership
2100 testing and eliminating duplicate entries.  Set objects also support
2101 mathematical operations like union, intersection, difference, and
2102 symmetric difference.
2103
2104 Here is a brief demonstration:
2105
2106 \begin{verbatim}
2107 >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
2108 >>> fruit = set(basket)               # create a set without duplicates
2109 >>> fruit
2110 set(['orange', 'pear', 'apple', 'banana'])
2111 >>> 'orange' in fruit                 # fast membership testing
2112 True
2113 >>> 'crabgrass' in fruit
2114 False
2115
2116 >>> # Demonstrate set operations on unique letters from two words
2117 ...
2118 >>> a = set('abracadabra')
2119 >>> b = set('alacazam')
2120 >>> a                                  # unique letters in a
2121 set(['a', 'r', 'b', 'c', 'd'])
2122 >>> a - b                              # letters in a but not in b
2123 set(['r', 'd', 'b'])
2124 >>> a | b                              # letters in either a or b
2125 set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
2126 >>> a & b                              # letters in both a and b
2127 set(['a', 'c'])
2128 >>> a ^ b                              # letters in a or b but not both
2129 set(['r', 'd', 'b', 'm', 'z', 'l'])
2130 \end{verbatim}
2131
2132
2133 \section{Dictionaries \label{dictionaries}}
2134
2135 Another useful data type built into Python is the
2136 \ulink{\emph{dictionary}}{../lib/typesmapping.html}.
2137 Dictionaries are sometimes found in other languages as ``associative
2138 memories'' or ``associative arrays''.  Unlike sequences, which are
2139 indexed by a range of numbers, dictionaries are indexed by \emph{keys},
2140 which can be any immutable type; strings and numbers can always be
2141 keys.  Tuples can be used as keys if they contain only strings,
2142 numbers, or tuples; if a tuple contains any mutable object either
2143 directly or indirectly, it cannot be used as a key.  You can't use
2144 lists as keys, since lists can be modified in place using methods like
2145 \method{append()} and \method{extend()} or modified with slice and
2146 indexed assignments.
2147
2148 It is best to think of a dictionary as an unordered set of
2149 \emph{key: value} pairs, with the requirement that the keys are unique
2150 (within one dictionary).
2151 A pair of braces creates an empty dictionary: \code{\{\}}.
2152 Placing a comma-separated list of key:value pairs within the
2153 braces adds initial key:value pairs to the dictionary; this is also the
2154 way dictionaries are written on output.
2155
2156 The main operations on a dictionary are storing a value with some key
2157 and extracting the value given the key.  It is also possible to delete
2158 a key:value pair
2159 with \code{del}.
2160 If you store using a key that is already in use, the old value
2161 associated with that key is forgotten.  It is an error to extract a
2162 value using a non-existent key.
2163
2164 The \method{keys()} method of a dictionary object returns a list of all
2165 the keys used in the dictionary, in arbitrary order (if you want it
2166 sorted, just apply the \method{sort()} method to the list of keys).  To
2167 check whether a single key is in the dictionary, either use the dictionary's
2168 \method{has_key()} method or the \keyword{in} keyword.
2169
2170 Here is a small example using a dictionary:
2171
2172 \begin{verbatim}
2173 >>> tel = {'jack': 4098, 'sape': 4139}
2174 >>> tel['guido'] = 4127
2175 >>> tel
2176 {'sape': 4139, 'guido': 4127, 'jack': 4098}
2177 >>> tel['jack']
2178 4098
2179 >>> del tel['sape']
2180 >>> tel['irv'] = 4127
2181 >>> tel
2182 {'guido': 4127, 'irv': 4127, 'jack': 4098}
2183 >>> tel.keys()
2184 ['guido', 'irv', 'jack']
2185 >>> tel.has_key('guido')
2186 True
2187 >>> 'guido' in tel
2188 True
2189 \end{verbatim}
2190
2191 The \function{dict()} constructor builds dictionaries directly from
2192 lists of key-value pairs stored as tuples.  When the pairs form a
2193 pattern, list comprehensions can compactly specify the key-value list.
2194
2195 \begin{verbatim}
2196 >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
2197 {'sape': 4139, 'jack': 4098, 'guido': 4127}
2198 >>> dict([(x, x**2) for x in (2, 4, 6)])     # use a list comprehension
2199 {2: 4, 4: 16, 6: 36}
2200 \end{verbatim}
2201
2202 Later in the tutorial, we will learn about Generator Expressions
2203 which are even better suited for the task of supplying key-values pairs to
2204 the \function{dict()} constructor.
2205
2206 When the keys are simple strings, it is sometimes easier to specify
2207 pairs using keyword arguments:
2208
2209 \begin{verbatim}
2210 >>> dict(sape=4139, guido=4127, jack=4098)
2211 {'sape': 4139, 'jack': 4098, 'guido': 4127}
2212 \end{verbatim}
2213
2214
2215 \section{Looping Techniques \label{loopidioms}}
2216
2217 When looping through dictionaries, the key and corresponding value can
2218 be retrieved at the same time using the \method{iteritems()} method.
2219
2220 \begin{verbatim}
2221 >>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
2222 >>> for k, v in knights.iteritems():
2223 ...     print k, v
2224 ...
2225 gallahad the pure
2226 robin the brave
2227 \end{verbatim}
2228  
2229 When looping through a sequence, the position index and corresponding
2230 value can be retrieved at the same time using the
2231 \function{enumerate()} function.
2232
2233 \begin{verbatim} 
2234 >>> for i, v in enumerate(['tic', 'tac', 'toe']):
2235 ...     print i, v
2236 ...
2237 0 tic
2238 1 tac
2239 2 toe
2240 \end{verbatim}
2241
2242 To loop over two or more sequences at the same time, the entries
2243 can be paired with the \function{zip()} function.
2244
2245 \begin{verbatim}
2246 >>> questions = ['name', 'quest', 'favorite color']
2247 >>> answers = ['lancelot', 'the holy grail', 'blue']
2248 >>> for q, a in zip(questions, answers):
2249 ...     print 'What is your %s?  It is %s.' % (q, a)
2250 ...     
2251 What is your name?  It is lancelot.
2252 What is your quest?  It is the holy grail.
2253 What is your favorite color?  It is blue.
2254 \end{verbatim}
2255
2256 To loop over a sequence in reverse, first specify the sequence
2257 in a forward direction and then call the \function{reversed()}
2258 function.
2259
2260 \begin{verbatim}
2261 >>> for i in reversed(xrange(1,10,2)):
2262 ...     print i
2263 ...
2264 9
2265 7
2266 5
2267 3
2268 1
2269 \end{verbatim}
2270
2271 To loop over a sequence in sorted order, use the \function{sorted()}
2272 function which returns a new sorted list while leaving the source
2273 unaltered.
2274
2275 \begin{verbatim}
2276 >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
2277 >>> for f in sorted(set(basket)):
2278 ...     print f
2279 ...     
2280 apple
2281 banana
2282 orange
2283 pear
2284 \end{verbatim}
2285
2286 \section{More on Conditions \label{conditions}}
2287
2288 The conditions used in \code{while} and \code{if} statements can
2289 contain any operators, not just comparisons.
2290
2291 The comparison operators \code{in} and \code{not in} check whether a value
2292 occurs (does not occur) in a sequence.  The operators \code{is} and
2293 \code{is not} compare whether two objects are really the same object; this
2294 only matters for mutable objects like lists.  All comparison operators
2295 have the same priority, which is lower than that of all numerical
2296 operators.
2297
2298 Comparisons can be chained.  For example, \code{a < b == c} tests
2299 whether \code{a} is less than \code{b} and moreover \code{b} equals
2300 \code{c}.
2301
2302 Comparisons may be combined using the Boolean operators \code{and} and
2303 \code{or}, and the outcome of a comparison (or of any other Boolean
2304 expression) may be negated with \code{not}.  These have lower
2305 priorities than comparison operators; between them, \code{not} has
2306 the highest priority and \code{or} the lowest, so that
2307 \code{A and not B or C} is equivalent to \code{(A and (not B)) or C}.
2308 As always, parentheses can be used to express the desired composition.
2309
2310 The Boolean operators \code{and} and \code{or} are so-called
2311 \emph{short-circuit} operators: their arguments are evaluated from
2312 left to right, and evaluation stops as soon as the outcome is
2313 determined.  For example, if \code{A} and \code{C} are true but
2314 \code{B} is false, \code{A and B and C} does not evaluate the
2315 expression \code{C}.  When used as a general value and not as a
2316 Boolean, the return value of a short-circuit operator is the last
2317 evaluated argument.
2318
2319 It is possible to assign the result of a comparison or other Boolean
2320 expression to a variable.  For example,
2321
2322 \begin{verbatim}
2323 >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
2324 >>> non_null = string1 or string2 or string3
2325 >>> non_null
2326 'Trondheim'
2327 \end{verbatim}
2328
2329 Note that in Python, unlike C, assignment cannot occur inside expressions.
2330 C programmers may grumble about this, but it avoids a common class of
2331 problems encountered in C programs: typing \code{=} in an expression when
2332 \code{==} was intended.
2333
2334
2335 \section{Comparing Sequences and Other Types \label{comparing}}
2336
2337 Sequence objects may be compared to other objects with the same
2338 sequence type.  The comparison uses \emph{lexicographical} ordering:
2339 first the first two items are compared, and if they differ this
2340 determines the outcome of the comparison; if they are equal, the next
2341 two items are compared, and so on, until either sequence is exhausted.
2342 If two items to be compared are themselves sequences of the same type,
2343 the lexicographical comparison is carried out recursively.  If all
2344 items of two sequences compare equal, the sequences are considered
2345 equal.  If one sequence is an initial sub-sequence of the other, the
2346 shorter sequence is the smaller (lesser) one.  Lexicographical
2347 ordering for strings uses the \ASCII{} ordering for individual
2348 characters.  Some examples of comparisons between sequences of the
2349 same type:
2350
2351 \begin{verbatim}
2352 (1, 2, 3)              < (1, 2, 4)
2353 [1, 2, 3]              < [1, 2, 4]
2354 'ABC' < 'C' < 'Pascal' < 'Python'
2355 (1, 2, 3, 4)           < (1, 2, 4)
2356 (1, 2)                 < (1, 2, -1)
2357 (1, 2, 3)             == (1.0, 2.0, 3.0)
2358 (1, 2, ('aa', 'ab'))   < (1, 2, ('abc', 'a'), 4)
2359 \end{verbatim}
2360
2361 Note that comparing objects of different types is legal.  The outcome
2362 is deterministic but arbitrary: the types are ordered by their name.
2363 Thus, a list is always smaller than a string, a string is always
2364 smaller than a tuple, etc.  \footnote{
2365         The rules for comparing objects of different types should
2366         not be relied upon; they may change in a future version of
2367         the language.
2368 } Mixed numeric types are compared according to their numeric value, so
2369 0 equals 0.0, etc.
2370
2371
2372 \chapter{Modules \label{modules}}
2373
2374 If you quit from the Python interpreter and enter it again, the
2375 definitions you have made (functions and variables) are lost.
2376 Therefore, if you want to write a somewhat longer program, you are
2377 better off using a text editor to prepare the input for the interpreter
2378 and running it with that file as input instead.  This is known as creating a
2379 \emph{script}.  As your program gets longer, you may want to split it
2380 into several files for easier maintenance.  You may also want to use a
2381 handy function that you've written in several programs without copying
2382 its definition into each program.
2383
2384 To support this, Python has a way to put definitions in a file and use
2385 them in a script or in an interactive instance of the interpreter.
2386 Such a file is called a \emph{module}; definitions from a module can be
2387 \emph{imported} into other modules or into the \emph{main} module (the
2388 collection of variables that you have access to in a script
2389 executed at the top level
2390 and in calculator mode).
2391
2392 A module is a file containing Python definitions and statements.  The
2393 file name is the module name with the suffix \file{.py} appended.  Within
2394 a module, the module's name (as a string) is available as the value of
2395 the global variable \code{__name__}.  For instance, use your favorite text
2396 editor to create a file called \file{fibo.py} in the current directory
2397 with the following contents:
2398
2399 \begin{verbatim}
2400 # Fibonacci numbers module
2401
2402 def fib(n):    # write Fibonacci series up to n
2403     a, b = 0, 1
2404     while b < n:
2405         print b,
2406         a, b = b, a+b
2407
2408 def fib2(n): # return Fibonacci series up to n
2409     result = []
2410     a, b = 0, 1
2411     while b < n:
2412         result.append(b)
2413         a, b = b, a+b
2414     return result
2415 \end{verbatim}
2416
2417 Now enter the Python interpreter and import this module with the
2418 following command:
2419
2420 \begin{verbatim}
2421 >>> import fibo
2422 \end{verbatim}
2423
2424 This does not enter the names of the functions defined in \code{fibo} 
2425 directly in the current symbol table; it only enters the module name
2426 \code{fibo} there.
2427 Using the module name you can access the functions:
2428
2429 \begin{verbatim}
2430 >>> fibo.fib(1000)
2431 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
2432 >>> fibo.fib2(100)
2433 [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
2434 >>> fibo.__name__
2435 'fibo'
2436 \end{verbatim}
2437
2438 If you intend to use a function often you can assign it to a local name:
2439
2440 \begin{verbatim}
2441 >>> fib = fibo.fib
2442 >>> fib(500)
2443 1 1 2 3 5 8 13 21 34 55 89 144 233 377
2444 \end{verbatim}
2445
2446
2447 \section{More on Modules \label{moreModules}}
2448
2449 A module can contain executable statements as well as function
2450 definitions.
2451 These statements are intended to initialize the module.
2452 They are executed only the
2453 \emph{first} time the module is imported somewhere.\footnote{
2454         In fact function definitions are also `statements' that are
2455         `executed'; the execution enters the function name in the
2456         module's global symbol table.
2457 }
2458
2459 Each module has its own private symbol table, which is used as the
2460 global symbol table by all functions defined in the module.
2461 Thus, the author of a module can use global variables in the module
2462 without worrying about accidental clashes with a user's global
2463 variables.
2464 On the other hand, if you know what you are doing you can touch a
2465 module's global variables with the same notation used to refer to its
2466 functions,
2467 \code{modname.itemname}.
2468
2469 Modules can import other modules.  It is customary but not required to
2470 place all \keyword{import} statements at the beginning of a module (or
2471 script, for that matter).  The imported module names are placed in the
2472 importing module's global symbol table.
2473
2474 There is a variant of the \keyword{import} statement that imports
2475 names from a module directly into the importing module's symbol
2476 table.  For example:
2477
2478 \begin{verbatim}
2479 >>> from fibo import fib, fib2
2480 >>> fib(500)
2481 1 1 2 3 5 8 13 21 34 55 89 144 233 377
2482 \end{verbatim}
2483
2484 This does not introduce the module name from which the imports are taken
2485 in the local symbol table (so in the example, \code{fibo} is not
2486 defined).
2487
2488 There is even a variant to import all names that a module defines:
2489
2490 \begin{verbatim}
2491 >>> from fibo import *
2492 >>> fib(500)
2493 1 1 2 3 5 8 13 21 34 55 89 144 233 377
2494 \end{verbatim}
2495
2496 This imports all names except those beginning with an underscore
2497 (\code{_}).
2498
2499
2500 \subsection{The Module Search Path \label{searchPath}}
2501
2502 \indexiii{module}{search}{path}
2503 When a module named \module{spam} is imported, the interpreter searches
2504 for a file named \file{spam.py} in the current directory,
2505 and then in the list of directories specified by
2506 the environment variable \envvar{PYTHONPATH}.  This has the same syntax as
2507 the shell variable \envvar{PATH}, that is, a list of
2508 directory names.  When \envvar{PYTHONPATH} is not set, or when the file
2509 is not found there, the search continues in an installation-dependent
2510 default path; on \UNIX, this is usually \file{.:/usr/local/lib/python}.
2511
2512 Actually, modules are searched in the list of directories given by the 
2513 variable \code{sys.path} which is initialized from the directory 
2514 containing the input script (or the current directory),
2515 \envvar{PYTHONPATH} and the installation-dependent default.  This allows
2516 Python programs that know what they're doing to modify or replace the 
2517 module search path.  Note that because the directory containing the
2518 script being run is on the search path, it is important that the
2519 script not have the same name as a standard module, or Python will
2520 attempt to load the script as a module when that module is imported.
2521 This will generally be an error.  See section~\ref{standardModules},
2522 ``Standard Modules,'' for more information.
2523
2524
2525 \subsection{``Compiled'' Python files}
2526
2527 As an important speed-up of the start-up time for short programs that
2528 use a lot of standard modules, if a file called \file{spam.pyc} exists
2529 in the directory where \file{spam.py} is found, this is assumed to
2530 contain an already-``byte-compiled'' version of the module \module{spam}.
2531 The modification time of the version of \file{spam.py} used to create
2532 \file{spam.pyc} is recorded in \file{spam.pyc}, and the
2533 \file{.pyc} file is ignored if these don't match.
2534
2535 Normally, you don't need to do anything to create the
2536 \file{spam.pyc} file.  Whenever \file{spam.py} is successfully
2537 compiled, an attempt is made to write the compiled version to
2538 \file{spam.pyc}.  It is not an error if this attempt fails; if for any
2539 reason the file is not written completely, the resulting
2540 \file{spam.pyc} file will be recognized as invalid and thus ignored
2541 later.  The contents of the \file{spam.pyc} file are platform
2542 independent, so a Python module directory can be shared by machines of
2543 different architectures.
2544
2545 Some tips for experts:
2546
2547 \begin{itemize}
2548
2549 \item
2550 When the Python interpreter is invoked with the \programopt{-O} flag,
2551 optimized code is generated and stored in \file{.pyo} files.  The
2552 optimizer currently doesn't help much; it only removes
2553 \keyword{assert} statements.  When \programopt{-O} is used, \emph{all}
2554 bytecode is optimized; \code{.pyc} files are ignored and \code{.py}
2555 files are compiled to optimized bytecode.
2556
2557 \item
2558 Passing two \programopt{-O} flags to the Python interpreter
2559 (\programopt{-OO}) will cause the bytecode compiler to perform
2560 optimizations that could in some rare cases result in malfunctioning
2561 programs.  Currently only \code{__doc__} strings are removed from the
2562 bytecode, resulting in more compact \file{.pyo} files.  Since some
2563 programs may rely on having these available, you should only use this
2564 option if you know what you're doing.
2565
2566 \item
2567 A program doesn't run any faster when it is read from a \file{.pyc} or
2568 \file{.pyo} file than when it is read from a \file{.py} file; the only
2569 thing that's faster about \file{.pyc} or \file{.pyo} files is the
2570 speed with which they are loaded.
2571
2572 \item
2573 When a script is run by giving its name on the command line, the
2574 bytecode for the script is never written to a \file{.pyc} or
2575 \file{.pyo} file.  Thus, the startup time of a script may be reduced
2576 by moving most of its code to a module and having a small bootstrap
2577 script that imports that module.  It is also possible to name a
2578 \file{.pyc} or \file{.pyo} file directly on the command line.
2579
2580 \item
2581 It is possible to have a file called \file{spam.pyc} (or
2582 \file{spam.pyo} when \programopt{-O} is used) without a file
2583 \file{spam.py} for the same module.  This can be used to distribute a
2584 library of Python code in a form that is moderately hard to reverse
2585 engineer.
2586
2587 \item
2588 The module \ulink{\module{compileall}}{../lib/module-compileall.html}%
2589 {} \refstmodindex{compileall} can create \file{.pyc} files (or
2590 \file{.pyo} files when \programopt{-O} is used) for all modules in a
2591 directory.
2592
2593 \end{itemize}
2594
2595
2596 \section{Standard Modules \label{standardModules}}
2597
2598 Python comes with a library of standard modules, described in a separate
2599 document, the \citetitle[../lib/lib.html]{Python Library Reference}
2600 (``Library Reference'' hereafter).  Some modules are built into the
2601 interpreter; these provide access to operations that are not part of
2602 the core of the language but are nevertheless built in, either for
2603 efficiency or to provide access to operating system primitives such as
2604 system calls.  The set of such modules is a configuration option which
2605 also depends on the underlying platform  For example,
2606 the \module{amoeba} module is only provided on systems that somehow
2607 support Amoeba primitives.  One particular module deserves some
2608 attention: \ulink{\module{sys}}{../lib/module-sys.html}%
2609 \refstmodindex{sys}, which is built into every 
2610 Python interpreter.  The variables \code{sys.ps1} and
2611 \code{sys.ps2} define the strings used as primary and secondary
2612 prompts:
2613
2614 \begin{verbatim}
2615 >>> import sys
2616 >>> sys.ps1
2617 '>>> '
2618 >>> sys.ps2
2619 '... '
2620 >>> sys.ps1 = 'C> '
2621 C> print 'Yuck!'
2622 Yuck!
2623 C>
2624
2625 \end{verbatim}
2626
2627 These two variables are only defined if the interpreter is in
2628 interactive mode.
2629
2630 The variable \code{sys.path} is a list of strings that determines the
2631 interpreter's search path for modules. It is initialized to a default
2632 path taken from the environment variable \envvar{PYTHONPATH}, or from
2633 a built-in default if \envvar{PYTHONPATH} is not set.  You can modify
2634 it using standard list operations: 
2635
2636 \begin{verbatim}
2637 >>> import sys
2638 >>> sys.path.append('/ufs/guido/lib/python')
2639 \end{verbatim}
2640
2641 \section{The \function{dir()} Function \label{dir}}
2642
2643 The built-in function \function{dir()} is used to find out which names
2644 a module defines.  It returns a sorted list of strings:
2645
2646 \begin{verbatim}
2647 >>> import fibo, sys
2648 >>> dir(fibo)
2649 ['__name__', 'fib', 'fib2']
2650 >>> dir(sys)
2651 ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
2652  '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv', 
2653  'builtin_module_names', 'byteorder', 'callstats', 'copyright',
2654  'displayhook', 'exc_clear', 'exc_info', 'exc_type', 'excepthook',
2655  'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
2656  'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
2657  'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
2658  'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
2659  'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
2660  'version', 'version_info', 'warnoptions']
2661 \end{verbatim}
2662
2663 Without arguments, \function{dir()} lists the names you have defined
2664 currently:
2665
2666 \begin{verbatim}
2667 >>> a = [1, 2, 3, 4, 5]
2668 >>> import fibo
2669 >>> fib = fibo.fib
2670 >>> dir()
2671 ['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']
2672 \end{verbatim}
2673
2674 Note that it lists all types of names: variables, modules, functions, etc.
2675
2676 \function{dir()} does not list the names of built-in functions and
2677 variables.  If you want a list of those, they are defined in the
2678 standard module \module{__builtin__}\refbimodindex{__builtin__}:
2679
2680 \begin{verbatim}
2681 >>> import __builtin__
2682 >>> dir(__builtin__)
2683 ['ArithmeticError', 'AssertionError', 'AttributeError', 'DeprecationWarning',
2684  'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
2685  'FloatingPointError', 'FutureWarning', 'IOError', 'ImportError',
2686  'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
2687  'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
2688  'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning',
2689  'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
2690  'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError',
2691  'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
2692  'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
2693  'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
2694  'UserWarning', 'ValueError', 'Warning', 'WindowsError',
2695  'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
2696  '__name__', 'abs', 'apply', 'basestring', 'bool', 'buffer',
2697  'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile',
2698  'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
2699  'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
2700  'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex',
2701  'id', 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
2702  'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min',
2703  'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range',
2704  'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round', 'set',
2705  'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
2706  'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
2707 \end{verbatim}
2708
2709
2710 \section{Packages \label{packages}}
2711
2712 Packages are a way of structuring Python's module namespace
2713 by using ``dotted module names''.  For example, the module name
2714 \module{A.B} designates a submodule named \samp{B} in a package named
2715 \samp{A}.  Just like the use of modules saves the authors of different
2716 modules from having to worry about each other's global variable names,
2717 the use of dotted module names saves the authors of multi-module
2718 packages like NumPy or the Python Imaging Library from having to worry
2719 about each other's module names.
2720
2721 Suppose you want to design a collection of modules (a ``package'') for
2722 the uniform handling of sound files and sound data.  There are many
2723 different sound file formats (usually recognized by their extension,
2724 for example: \file{.wav}, \file{.aiff}, \file{.au}), so you may need
2725 to create and maintain a growing collection of modules for the
2726 conversion between the various file formats.  There are also many
2727 different operations you might want to perform on sound data (such as
2728 mixing, adding echo, applying an equalizer function, creating an
2729 artificial stereo effect), so in addition you will be writing a
2730 never-ending stream of modules to perform these operations.  Here's a
2731 possible structure for your package (expressed in terms of a
2732 hierarchical filesystem):
2733
2734 \begin{verbatim}
2735 Sound/                          Top-level package
2736       __init__.py               Initialize the sound package
2737       Formats/                  Subpackage for file format conversions
2738               __init__.py
2739               wavread.py
2740               wavwrite.py
2741               aiffread.py
2742               aiffwrite.py
2743               auread.py
2744               auwrite.py
2745               ...
2746       Effects/                  Subpackage for sound effects
2747               __init__.py
2748               echo.py
2749               surround.py
2750               reverse.py
2751               ...
2752       Filters/                  Subpackage for filters
2753               __init__.py
2754               equalizer.py
2755               vocoder.py
2756               karaoke.py
2757               ...
2758 \end{verbatim}
2759
2760 When importing the package, Python searches through the directories
2761 on \code{sys.path} looking for the package subdirectory.
2762
2763 The \file{__init__.py} files are required to make Python treat the
2764 directories as containing packages; this is done to prevent
2765 directories with a common name, such as \samp{string}, from
2766 unintentionally hiding valid modules that occur later on the module
2767 search path. In the simplest case, \file{__init__.py} can just be an
2768 empty file, but it can also execute initialization code for the
2769 package or set the \code{__all__} variable, described later.
2770
2771 Users of the package can import individual modules from the
2772 package, for example:
2773
2774 \begin{verbatim}
2775 import Sound.Effects.echo
2776 \end{verbatim}
2777
2778 This loads the submodule \module{Sound.Effects.echo}.  It must be referenced
2779 with its full name.
2780
2781 \begin{verbatim}
2782 Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4)
2783 \end{verbatim}
2784
2785 An alternative way of importing the submodule is:
2786
2787 \begin{verbatim}
2788 from Sound.Effects import echo
2789 \end{verbatim}
2790
2791 This also loads the submodule \module{echo}, and makes it available without
2792 its package prefix, so it can be used as follows:
2793
2794 \begin{verbatim}
2795 echo.echofilter(input, output, delay=0.7, atten=4)
2796 \end{verbatim}
2797
2798 Yet another variation is to import the desired function or variable directly:
2799
2800 \begin{verbatim}
2801 from Sound.Effects.echo import echofilter
2802 \end{verbatim}
2803
2804 Again, this loads the submodule \module{echo}, but this makes its function
2805 \function{echofilter()} directly available:
2806
2807 \begin{verbatim}
2808 echofilter(input, output, delay=0.7, atten=4)
2809 \end{verbatim}
2810
2811 Note that when using \code{from \var{package} import \var{item}}, the
2812 item can be either a submodule (or subpackage) of the package, or some 
2813 other name defined in the package, like a function, class or
2814 variable.  The \code{import} statement first tests whether the item is
2815 defined in the package; if not, it assumes it is a module and attempts
2816 to load it.  If it fails to find it, an
2817 \exception{ImportError} exception is raised.
2818
2819 Contrarily, when using syntax like \code{import