| \documentclass{manual} |
| \usepackage[T1]{fontenc} |
| |
| % Things to do: |
| % Add a section on file I/O |
| % Write a chapter entitled ``Some Useful Modules'' |
| % --re, math+cmath |
| % Should really move the Python startup file info to an appendix |
| |
| \title{Python Tutorial} |
| |
| \input{boilerplate} |
| |
| \begin{document} |
| |
| \maketitle |
| |
| \ifhtml |
| \chapter*{Front Matter\label{front}} |
| \fi |
| |
| \input{copyright} |
| |
| \begin{abstract} |
| |
| \noindent |
| Python is an easy to learn, powerful programming language. It has |
| efficient high-level data structures and a simple but effective |
| approach to object-oriented programming. Python's elegant syntax and |
| dynamic typing, together with its interpreted nature, make it an ideal |
| language for scripting and rapid application development in many areas |
| on most platforms. |
| |
| The Python interpreter and the extensive standard library are freely |
| available in source or binary form for all major platforms from the |
| Python Web site, \url{http://www.python.org/}, and can be freely |
| distributed. The same site also contains distributions of and |
| pointers to many free third party Python modules, programs and tools, |
| and additional documentation. |
| |
| The Python interpreter is easily extended with new functions and data |
| types implemented in C or \Cpp{} (or other languages callable from C). |
| Python is also suitable as an extension language for customizable |
| applications. |
| |
| This tutorial introduces the reader informally to the basic concepts |
| and features of the Python language and system. It helps to have a |
| Python interpreter handy for hands-on experience, but all examples are |
| self-contained, so the tutorial can be read off-line as well. |
| |
| For a description of standard objects and modules, see the |
| \citetitle[../lib/lib.html]{Python Library Reference} document. The |
| \citetitle[../ref/ref.html]{Python Reference Manual} gives a more |
| formal definition of the language. To write extensions in C or |
| \Cpp, read \citetitle[../ext/ext.html]{Extending and Embedding the |
| Python Interpreter} and \citetitle[../api/api.html]{Python/C API |
| Reference}. There are also several books covering Python in depth. |
| |
| This tutorial does not attempt to be comprehensive and cover every |
| single feature, or even every commonly used feature. Instead, it |
| introduces many of Python's most noteworthy features, and will give |
| you a good idea of the language's flavor and style. After reading it, |
| you will be able to read and write Python modules and programs, and |
| you will be ready to learn more about the various Python library |
| modules described in the \citetitle[../lib/lib.html]{Python Library |
| Reference}. |
| |
| \end{abstract} |
| |
| \tableofcontents |
| |
| |
| \chapter{Whetting Your Appetite \label{intro}} |
| |
| If you ever wrote a large shell script, you probably know this |
| feeling: you'd love to add yet another feature, but it's already so |
| slow, and so big, and so complicated; or the feature involves a system |
| call or other function that is only accessible from C \ldots Usually |
| the problem at hand isn't serious enough to warrant rewriting the |
| script in C; perhaps the problem requires variable-length strings or |
| other data types (like sorted lists of file names) that are easy in |
| the shell but lots of work to implement in C, or perhaps you're not |
| sufficiently familiar with C. |
| |
| Another situation: perhaps you have to work with several C libraries, |
| and the usual C write/compile/test/re-compile cycle is too slow. You |
| need to develop software more quickly. Possibly perhaps you've |
| written a program that could use an extension language, and you don't |
| want to design a language, write and debug an interpreter for it, then |
| tie it into your application. |
| |
| In such cases, Python may be just the language for you. Python is |
| simple to use, but it is a real programming language, offering much |
| more structure and support for large programs than the shell has. On |
| the other hand, it also offers much more error checking than C, and, |
| being a \emph{very-high-level language}, it has high-level data types |
| built in, such as flexible arrays and dictionaries that would cost you |
| days to implement efficiently in C. Because of its more general data |
| types Python is applicable to a much larger problem domain than |
| \emph{Awk} or even \emph{Perl}, yet many things are at least as easy |
| in Python as in those languages. |
| |
| Python allows you to split up your program in modules that can be |
| reused in other Python programs. It comes with a large collection of |
| standard modules that you can use as the basis of your programs --- or |
| as examples to start learning to program in Python. There are also |
| built-in modules that provide things like file I/O, system calls, |
| sockets, and even interfaces to graphical user interface toolkits like Tk. |
| |
| Python is an interpreted language, which can save you considerable time |
| during program development because no compilation and linking is |
| necessary. The interpreter can be used interactively, which makes it |
| easy to experiment with features of the language, to write throw-away |
| programs, or to test functions during bottom-up program development. |
| It is also a handy desk calculator. |
| |
| Python allows writing very compact and readable programs. Programs |
| written in Python are typically much shorter than equivalent C or |
| \Cpp{} programs, for several reasons: |
| \begin{itemize} |
| \item |
| the high-level data types allow you to express complex operations in a |
| single statement; |
| \item |
| statement grouping is done by indentation instead of begin/end |
| brackets; |
| \item |
| no variable or argument declarations are necessary. |
| \end{itemize} |
| |
| Python is \emph{extensible}: if you know how to program in C it is easy |
| to add a new built-in function or module to the interpreter, either to |
| perform critical operations at maximum speed, or to link Python |
| programs to libraries that may only be available in binary form (such |
| as a vendor-specific graphics library). Once you are really hooked, |
| you can link the Python interpreter into an application written in C |
| and use it as an extension or command language for that application. |
| |
| By the way, the language is named after the BBC show ``Monty Python's |
| Flying Circus'' and has nothing to do with nasty reptiles. Making |
| references to Monty Python skits in documentation is not only allowed, |
| it is encouraged! |
| |
| \section{Where From Here \label{where}} |
| |
| Now that you are all excited about Python, you'll want to examine it |
| in some more detail. Since the best way to learn a language is |
| using it, you are invited here to do so. |
| |
| In the next chapter, the mechanics of using the interpreter are |
| explained. This is rather mundane information, but essential for |
| trying out the examples shown later. |
| |
| The rest of the tutorial introduces various features of the Python |
| language and system through examples, beginning with simple |
| expressions, statements and data types, through functions and modules, |
| and finally touching upon advanced concepts like exceptions |
| and user-defined classes. |
| |
| \chapter{Using the Python Interpreter \label{using}} |
| |
| \section{Invoking the Interpreter \label{invoking}} |
| |
| The Python interpreter is usually installed as |
| \file{/usr/local/bin/python} on those machines where it is available; |
| putting \file{/usr/local/bin} in your \UNIX{} shell's search path |
| makes it possible to start it by typing the command |
| |
| \begin{verbatim} |
| python |
| \end{verbatim} |
| |
| to the shell. Since the choice of the directory where the interpreter |
| lives is an installation option, other places are possible; check with |
| your local Python guru or system administrator. (E.g., |
| \file{/usr/local/python} is a popular alternative location.) |
| |
| Typing an end-of-file character (\kbd{Control-D} on \UNIX, |
| \kbd{Control-Z} on DOS or Windows) at the primary prompt causes the |
| interpreter to exit with a zero exit status. If that doesn't work, |
| you can exit the interpreter by typing the following commands: |
| \samp{import sys; sys.exit()}. |
| |
| The interpreter's line-editing features usually aren't very |
| sophisticated. On \UNIX, whoever installed the interpreter may have |
| enabled support for the GNU readline library, which adds more |
| elaborate interactive editing and history features. Perhaps the |
| quickest check to see whether command line editing is supported is |
| typing Control-P to the first Python prompt you get. If it beeps, you |
| have command line editing; see Appendix \ref{interacting} for an |
| introduction to the keys. If nothing appears to happen, or if |
| \code{\^P} is echoed, command line editing isn't available; you'll |
| only be able to use backspace to remove characters from the current |
| line. |
| |
| The interpreter operates somewhat like the \UNIX{} shell: when called |
| with standard input connected to a tty device, it reads and executes |
| commands interactively; when called with a file name argument or with |
| a file as standard input, it reads and executes a \emph{script} from |
| that file. |
| |
| A third way of starting the interpreter is |
| \samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which |
| executes the statement(s) in \var{command}, analogous to the shell's |
| \programopt{-c} option. Since Python statements often contain spaces |
| or other characters that are special to the shell, it is best to quote |
| \var{command} in its entirety with double quotes. |
| |
| Note that there is a difference between \samp{python file} and |
| \samp{python <file}. In the latter case, input requests from the |
| program, such as calls to \code{input()} and \code{raw_input()}, are |
| satisfied from \emph{file}. Since this file has already been read |
| until the end by the parser before the program starts executing, the |
| program will encounter end-of-file immediately. In the former case |
| (which is usually what you want) they are satisfied from whatever file |
| or device is connected to standard input of the Python interpreter. |
| |
| When a script file is used, it is sometimes useful to be able to run |
| the script and enter interactive mode afterwards. This can be done by |
| passing \programopt{-i} before the script. (This does not work if the |
| script is read from standard input, for the same reason as explained |
| in the previous paragraph.) |
| |
| \subsection{Argument Passing \label{argPassing}} |
| |
| When known to the interpreter, the script name and additional |
| arguments thereafter are passed to the script in the variable |
| \code{sys.argv}, which is a list of strings. Its length is at least |
| one; when no script and no arguments are given, \code{sys.argv[0]} is |
| an empty string. When the script name is given as \code{'-'} (meaning |
| standard input), \code{sys.argv[0]} is set to \code{'-'}. When |
| \programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to |
| \code{'-c'}. Options found after \programopt{-c} \var{command} are |
| not consumed by the Python interpreter's option processing but left in |
| \code{sys.argv} for the command to handle. |
| |
| \subsection{Interactive Mode \label{interactive}} |
| |
| When commands are read from a tty, the interpreter is said to be in |
| \emph{interactive mode}. In this mode it prompts for the next command |
| with the \emph{primary prompt}, usually three greater-than signs |
| (\samp{>\code{>}>~}); for continuation lines it prompts with the |
| \emph{secondary prompt}, by default three dots (\samp{...~}). |
| The interpreter prints a welcome message stating its version number |
| and a copyright notice before printing the first prompt: |
| |
| \begin{verbatim} |
| python |
| Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5 |
| Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam |
| >>> |
| \end{verbatim} |
| |
| Continuation lines are needed when entering a multi-line construct. |
| As an example, take a look at this \keyword{if} statement: |
| |
| \begin{verbatim} |
| >>> the_world_is_flat = 1 |
| >>> if the_world_is_flat: |
| ... print "Be careful not to fall off!" |
| ... |
| Be careful not to fall off! |
| \end{verbatim} |
| |
| |
| \section{The Interpreter and Its Environment \label{interp}} |
| |
| \subsection{Error Handling \label{error}} |
| |
| When an error occurs, the interpreter prints an error |
| message and a stack trace. In interactive mode, it then returns to |
| the primary prompt; when input came from a file, it exits with a |
| nonzero exit status after printing |
| the stack trace. (Exceptions handled by an \code{except} clause in a |
| \code{try} statement are not errors in this context.) Some errors are |
| unconditionally fatal and cause an exit with a nonzero exit; this |
| applies to internal inconsistencies and some cases of running out of |
| memory. All error messages are written to the standard error stream; |
| normal output from the executed commands is written to standard |
| output. |
| |
| Typing the interrupt character (usually Control-C or DEL) to the |
| primary or secondary prompt cancels the input and returns to the |
| primary prompt.\footnote{ |
| A problem with the GNU Readline package may prevent this. |
| } |
| Typing an interrupt while a command is executing raises the |
| \code{KeyboardInterrupt} exception, which may be handled by a |
| \code{try} statement. |
| |
| \subsection{Executable Python Scripts \label{scripts}} |
| |
| On BSD'ish \UNIX{} systems, Python scripts can be made directly |
| executable, like shell scripts, by putting the line |
| |
| \begin{verbatim} |
| #! /usr/bin/env python |
| \end{verbatim} |
| |
| (assuming that the interpreter is on the user's \envvar{PATH}) at the |
| beginning of the script and giving the file an executable mode. The |
| \samp{\#!} must be the first two characters of the file. Note that |
| the hash, or pound, character, \character{\#}, is used to start a |
| comment in Python. |
| |
| \subsection{The Interactive Startup File \label{startup}} |
| |
| % XXX This should probably be dumped in an appendix, since most people |
| % don't use Python interactively in non-trivial ways. |
| |
| When you use Python interactively, it is frequently handy to have some |
| standard commands executed every time the interpreter is started. You |
| can do this by setting an environment variable named |
| \envvar{PYTHONSTARTUP} to the name of a file containing your start-up |
| commands. This is similar to the \file{.profile} feature of the |
| \UNIX{} shells. |
| |
| This file is only read in interactive sessions, not when Python reads |
| commands from a script, and not when \file{/dev/tty} is given as the |
| explicit source of commands (which otherwise behaves like an |
| interactive session). It is executed in the same namespace where |
| interactive commands are executed, so that objects that it defines or |
| imports can be used without qualification in the interactive session. |
| You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in |
| this file. |
| |
| If you want to read an additional start-up file from the current |
| directory, you can program this in the global start-up file using code |
| like \samp{if os.path.isfile('.pythonrc.py'): |
| execfile('.pythonrc.py')}. If you want to use the startup file in a |
| script, you must do this explicitly in the script: |
| |
| \begin{verbatim} |
| import os |
| filename = os.environ.get('PYTHONSTARTUP') |
| if filename and os.path.isfile(filename): |
| execfile(filename) |
| \end{verbatim} |
| |
| |
| \chapter{An Informal Introduction to Python \label{informal}} |
| |
| In the following examples, input and output are distinguished by the |
| presence or absence of prompts (\samp{>\code{>}>~} and \samp{...~}): to repeat |
| the example, you must type everything after the prompt, when the |
| prompt appears; lines that do not begin with a prompt are output from |
| the interpreter. % |
| %\footnote{ |
| % I'd prefer to use different fonts to distinguish input |
| % from output, but the amount of LaTeX hacking that would require |
| % is currently beyond my ability. |
| %} |
| Note that a secondary prompt on a line by itself in an example means |
| you must type a blank line; this is used to end a multi-line command. |
| |
| Many of the examples in this manual, even those entered at the |
| interactive prompt, include comments. Comments in Python start with |
| the hash character, \character{\#}, and extend to the end of the |
| physical line. A comment may appear at the start of a line or |
| following whitespace or code, but not within a string literal. A hash |
| character within a string literal is just a hash character. |
| |
| Some examples: |
| |
| \begin{verbatim} |
| # this is the first comment |
| SPAM = 1 # and this is the second comment |
| # ... and now a third! |
| STRING = "# This is not a comment." |
| \end{verbatim} |
| |
| |
| \section{Using Python as a Calculator \label{calculator}} |
| |
| Let's try some simple Python commands. Start the interpreter and wait |
| for the primary prompt, \samp{>\code{>}>~}. (It shouldn't take long.) |
| |
| \subsection{Numbers \label{numbers}} |
| |
| The interpreter acts as a simple calculator: you can type an |
| expression at it and it will write the value. Expression syntax is |
| straightforward: the operators \code{+}, \code{-}, \code{*} and |
| \code{/} work just like in most other languages (for example, Pascal |
| or C); parentheses can be used for grouping. For example: |
| |
| \begin{verbatim} |
| >>> 2+2 |
| 4 |
| >>> # This is a comment |
| ... 2+2 |
| 4 |
| >>> 2+2 # and a comment on the same line as code |
| 4 |
| >>> (50-5*6)/4 |
| 5 |
| >>> # Integer division returns the floor: |
| ... 7/3 |
| 2 |
| >>> 7/-3 |
| -3 |
| \end{verbatim} |
| |
| Like in C, the equal sign (\character{=}) is used to assign a value to a |
| variable. The value of an assignment is not written: |
| |
| \begin{verbatim} |
| >>> width = 20 |
| >>> height = 5*9 |
| >>> width * height |
| 900 |
| \end{verbatim} |
| |
| A value can be assigned to several variables simultaneously: |
| |
| \begin{verbatim} |
| >>> x = y = z = 0 # Zero x, y and z |
| >>> x |
| 0 |
| >>> y |
| 0 |
| >>> z |
| 0 |
| \end{verbatim} |
| |
| There is full support for floating point; operators with mixed type |
| operands convert the integer operand to floating point: |
| |
| \begin{verbatim} |
| >>> 3 * 3.75 / 1.5 |
| 7.5 |
| >>> 7.0 / 2 |
| 3.5 |
| \end{verbatim} |
| |
| Complex numbers are also supported; imaginary numbers are written with |
| a suffix of \samp{j} or \samp{J}. Complex numbers with a nonzero |
| real component are written as \samp{(\var{real}+\var{imag}j)}, or can |
| be created with the \samp{complex(\var{real}, \var{imag})} function. |
| |
| \begin{verbatim} |
| >>> 1j * 1J |
| (-1+0j) |
| >>> 1j * complex(0,1) |
| (-1+0j) |
| >>> 3+1j*3 |
| (3+3j) |
| >>> (3+1j)*3 |
| (9+3j) |
| >>> (1+2j)/(1+1j) |
| (1.5+0.5j) |
| \end{verbatim} |
| |
| Complex numbers are always represented as two floating point numbers, |
| the real and imaginary part. To extract these parts from a complex |
| number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}. |
| |
| \begin{verbatim} |
| >>> a=1.5+0.5j |
| >>> a.real |
| 1.5 |
| >>> a.imag |
| 0.5 |
| \end{verbatim} |
| |
| The conversion functions to floating point and integer |
| (\function{float()}, \function{int()} and \function{long()}) don't |
| work for complex numbers --- there is no one correct way to convert a |
| complex number to a real number. Use \code{abs(\var{z})} to get its |
| magnitude (as a float) or \code{z.real} to get its real part. |
| |
| \begin{verbatim} |
| >>> a=3.0+4.0j |
| >>> float(a) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: can't convert complex to float; use e.g. abs(z) |
| >>> a.real |
| 3.0 |
| >>> a.imag |
| 4.0 |
| >>> abs(a) # sqrt(a.real**2 + a.imag**2) |
| 5.0 |
| >>> |
| \end{verbatim} |
| |
| In interactive mode, the last printed expression is assigned to the |
| variable \code{_}. This means that when you are using Python as a |
| desk calculator, it is somewhat easier to continue calculations, for |
| example: |
| |
| \begin{verbatim} |
| >>> tax = 12.5 / 100 |
| >>> price = 100.50 |
| >>> price * tax |
| 12.5625 |
| >>> price + _ |
| 113.0625 |
| >>> round(_, 2) |
| 113.06 |
| >>> |
| \end{verbatim} |
| |
| This variable should be treated as read-only by the user. Don't |
| explicitly assign a value to it --- you would create an independent |
| local variable with the same name masking the built-in variable with |
| its magic behavior. |
| |
| \subsection{Strings \label{strings}} |
| |
| Besides numbers, Python can also manipulate strings, which can be |
| expressed in several ways. They can be enclosed in single quotes or |
| double quotes: |
| |
| \begin{verbatim} |
| >>> 'spam eggs' |
| 'spam eggs' |
| >>> 'doesn\'t' |
| "doesn't" |
| >>> "doesn't" |
| "doesn't" |
| >>> '"Yes," he said.' |
| '"Yes," he said.' |
| >>> "\"Yes,\" he said." |
| '"Yes," he said.' |
| >>> '"Isn\'t," she said.' |
| '"Isn\'t," she said.' |
| \end{verbatim} |
| |
| String literals can span multiple lines in several ways. Continuation |
| lines can be used, with a backslash as the last character on the line |
| indicating that the next line is a logical continuation of the line: |
| |
| \begin{verbatim} |
| hello = "This is a rather long string containing\n\ |
| several lines of text just as you would do in C.\n\ |
| Note that whitespace at the beginning of the line is\ |
| significant." |
| |
| print hello |
| \end{verbatim} |
| |
| Note that newlines would still need to be embedded in the string using |
| \code{\e n}; the newline following the trailing backslash is |
| discarded. This example would print the following: |
| |
| \begin{verbatim} |
| This is a rather long string containing |
| several lines of text just as you would do in C. |
| Note that whitespace at the beginning of the line is significant. |
| \end{verbatim} |
| |
| If we make the string literal a ``raw'' string, however, the |
| \code{\e n} sequences are not converted to newlines, but the backslash |
| at the end of the line, and the newline character in the source, are |
| both included in the string as data. Thus, the example: |
| |
| \begin{verbatim} |
| hello = r"This is a rather long string containing\n\ |
| several lines of text much as you would do in C." |
| |
| print hello |
| \end{verbatim} |
| |
| would print: |
| |
| \begin{verbatim} |
| This is a rather long string containing\n\ |
| several lines of text much as you would do in C. |
| \end{verbatim} |
| |
| Or, strings can be surrounded in a pair of matching triple-quotes: |
| \code{"""} or \code{'\code{'}'}. End of lines do not need to be escaped |
| when using triple-quotes, but they will be included in the string. |
| |
| \begin{verbatim} |
| print """ |
| Usage: thingy [OPTIONS] |
| -h Display this usage message |
| -H hostname Hostname to connect to |
| """ |
| \end{verbatim} |
| |
| produces the following output: |
| |
| \begin{verbatim} |
| Usage: thingy [OPTIONS] |
| -h Display this usage message |
| -H hostname Hostname to connect to |
| \end{verbatim} |
| |
| The interpreter prints the result of string operations in the same way |
| as they are typed for input: inside quotes, and with quotes and other |
| funny characters escaped by backslashes, to show the precise |
| value. The string is enclosed in double quotes if the string contains |
| a single quote and no double quotes, else it's enclosed in single |
| quotes. (The \keyword{print} statement, described later, can be used |
| to write strings without quotes or escapes.) |
| |
| Strings can be concatenated (glued together) with the |
| \code{+} operator, and repeated with \code{*}: |
| |
| \begin{verbatim} |
| >>> word = 'Help' + 'A' |
| >>> word |
| 'HelpA' |
| >>> '<' + word*5 + '>' |
| '<HelpAHelpAHelpAHelpAHelpA>' |
| \end{verbatim} |
| |
| Two string literals next to each other are automatically concatenated; |
| the first line above could also have been written \samp{word = 'Help' |
| 'A'}; this only works with two literals, not with arbitrary string |
| expressions: |
| |
| \begin{verbatim} |
| >>> import string |
| >>> 'str' 'ing' # <- This is ok |
| 'string' |
| >>> string.strip('str') + 'ing' # <- This is ok |
| 'string' |
| >>> string.strip('str') 'ing' # <- This is invalid |
| File "<stdin>", line 1, in ? |
| string.strip('str') 'ing' |
| ^ |
| SyntaxError: invalid syntax |
| \end{verbatim} |
| |
| Strings can be subscripted (indexed); like in C, the first character |
| of a string has subscript (index) 0. There is no separate character |
| type; a character is simply a string of size one. Like in Icon, |
| substrings can be specified with the \emph{slice notation}: two indices |
| separated by a colon. |
| |
| \begin{verbatim} |
| >>> word[4] |
| 'A' |
| >>> word[0:2] |
| 'He' |
| >>> word[2:4] |
| 'lp' |
| \end{verbatim} |
| |
| Unlike a C string, Python strings cannot be changed. Assigning to an |
| indexed position in the string results in an error: |
| |
| \begin{verbatim} |
| >>> word[0] = 'x' |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: object doesn't support item assignment |
| >>> word[:1] = 'Splat' |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: object doesn't support slice assignment |
| \end{verbatim} |
| |
| However, creating a new string with the combined content is easy and |
| efficient: |
| |
| \begin{verbatim} |
| >>> 'x' + word[1:] |
| 'xelpA' |
| >>> 'Splat' + word[4] |
| 'SplatA' |
| \end{verbatim} |
| |
| Slice indices have useful defaults; an omitted first index defaults to |
| zero, an omitted second index defaults to the size of the string being |
| sliced. |
| |
| \begin{verbatim} |
| >>> word[:2] # The first two characters |
| 'He' |
| >>> word[2:] # All but the first two characters |
| 'lpA' |
| \end{verbatim} |
| |
| Here's a useful invariant of slice operations: |
| \code{s[:i] + s[i:]} equals \code{s}. |
| |
| \begin{verbatim} |
| >>> word[:2] + word[2:] |
| 'HelpA' |
| >>> word[:3] + word[3:] |
| 'HelpA' |
| \end{verbatim} |
| |
| Degenerate slice indices are handled gracefully: an index that is too |
| large is replaced by the string size, an upper bound smaller than the |
| lower bound returns an empty string. |
| |
| \begin{verbatim} |
| >>> word[1:100] |
| 'elpA' |
| >>> word[10:] |
| '' |
| >>> word[2:1] |
| '' |
| \end{verbatim} |
| |
| Indices may be negative numbers, to start counting from the right. |
| For example: |
| |
| \begin{verbatim} |
| >>> word[-1] # The last character |
| 'A' |
| >>> word[-2] # The last-but-one character |
| 'p' |
| >>> word[-2:] # The last two characters |
| 'pA' |
| >>> word[:-2] # All but the last two characters |
| 'Hel' |
| \end{verbatim} |
| |
| But note that -0 is really the same as 0, so it does not count from |
| the right! |
| |
| \begin{verbatim} |
| >>> word[-0] # (since -0 equals 0) |
| 'H' |
| \end{verbatim} |
| |
| Out-of-range negative slice indices are truncated, but don't try this |
| for single-element (non-slice) indices: |
| |
| \begin{verbatim} |
| >>> word[-100:] |
| 'HelpA' |
| >>> word[-10] # error |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| IndexError: string index out of range |
| \end{verbatim} |
| |
| The best way to remember how slices work is to think of the indices as |
| pointing \emph{between} characters, with the left edge of the first |
| character numbered 0. Then the right edge of the last character of a |
| string of \var{n} characters has index \var{n}, for example: |
| |
| \begin{verbatim} |
| +---+---+---+---+---+ |
| | H | e | l | p | A | |
| +---+---+---+---+---+ |
| 0 1 2 3 4 5 |
| -5 -4 -3 -2 -1 |
| \end{verbatim} |
| |
| The first row of numbers gives the position of the indices 0...5 in |
| the string; the second row gives the corresponding negative indices. |
| The slice from \var{i} to \var{j} consists of all characters between |
| the edges labeled \var{i} and \var{j}, respectively. |
| |
| For non-negative indices, the length of a slice is the difference of |
| the indices, if both are within bounds. For example, the length of |
| \code{word[1:3]} is 2. |
| |
| The built-in function \function{len()} returns the length of a string: |
| |
| \begin{verbatim} |
| >>> s = 'supercalifragilisticexpialidocious' |
| >>> len(s) |
| 34 |
| \end{verbatim} |
| |
| |
| \subsection{Unicode Strings \label{unicodeStrings}} |
| \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} |
| |
| Starting with Python 2.0 a new data type for storing text data is |
| available to the programmer: the Unicode object. It can be used to |
| store and manipulate Unicode data (see \url{http://www.unicode.org/}) |
| and integrates well with the existing string objects providing |
| auto-conversions where necessary. |
| |
| Unicode has the advantage of providing one ordinal for every character |
| in every script used in modern and ancient texts. Previously, there |
| were only 256 possible ordinals for script characters and texts were |
| typically bound to a code page which mapped the ordinals to script |
| characters. This lead to very much confusion especially with respect |
| to internationalization (usually written as \samp{i18n} --- |
| \character{i} + 18 characters + \character{n}) of software. Unicode |
| solves these problems by defining one code page for all scripts. |
| |
| Creating Unicode strings in Python is just as simple as creating |
| normal strings: |
| |
| \begin{verbatim} |
| >>> u'Hello World !' |
| u'Hello World !' |
| \end{verbatim} |
| |
| The small \character{u} in front of the quote indicates that an |
| Unicode string is supposed to be created. If you want to include |
| special characters in the string, you can do so by using the Python |
| \emph{Unicode-Escape} encoding. The following example shows how: |
| |
| \begin{verbatim} |
| >>> u'Hello\u0020World !' |
| u'Hello World !' |
| \end{verbatim} |
| |
| The escape sequence \code{\e u0020} indicates to insert the Unicode |
| character with the ordinal value 0x0020 (the space character) at the |
| given position. |
| |
| Other characters are interpreted by using their respective ordinal |
| values directly as Unicode ordinals. If you have literal strings |
| in the standard Latin-1 encoding that is used in many Western countries, |
| you will find it convenient that the lower 256 characters |
| of Unicode are the same as the 256 characters of Latin-1. |
| |
| For experts, there is also a raw mode just like the one for normal |
| strings. You have to prefix the opening quote with 'ur' to have |
| Python use the \emph{Raw-Unicode-Escape} encoding. It will only apply |
| the above \code{\e uXXXX} conversion if there is an uneven number of |
| backslashes in front of the small 'u'. |
| |
| \begin{verbatim} |
| >>> ur'Hello\u0020World !' |
| u'Hello World !' |
| >>> ur'Hello\\u0020World !' |
| u'Hello\\\\u0020World !' |
| \end{verbatim} |
| |
| The raw mode is most useful when you have to enter lots of |
| backslashes, as can be necessary in regular expressions. |
| |
| Apart from these standard encodings, Python provides a whole set of |
| other ways of creating Unicode strings on the basis of a known |
| encoding. |
| |
| The built-in function \function{unicode()}\bifuncindex{unicode} provides |
| access to all registered Unicode codecs (COders and DECoders). Some of |
| the more well known encodings which these codecs can convert are |
| \emph{Latin-1}, \emph{ASCII}, \emph{UTF-8}, and \emph{UTF-16}. |
| The latter two are variable-length encodings that store each Unicode |
| character in one or more bytes. The default encoding is |
| normally set to ASCII, which passes through characters in the range |
| 0 to 127 and rejects any other characters with an error. |
| When a Unicode string is printed, written to a file, or converted |
| with \function{str()}, conversion takes place using this default encoding. |
| |
| \begin{verbatim} |
| >>> u"abc" |
| u'abc' |
| >>> str(u"abc") |
| 'abc' |
| >>> u"äöü" |
| u'\xe4\xf6\xfc' |
| >>> str(u"äöü") |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| UnicodeError: ASCII encoding error: ordinal not in range(128) |
| \end{verbatim} |
| |
| To convert a Unicode string into an 8-bit string using a specific |
| encoding, Unicode objects provide an \function{encode()} method |
| that takes one argument, the name of the encoding. Lowercase names |
| for encodings are preferred. |
| |
| \begin{verbatim} |
| >>> u"äöü".encode('utf-8') |
| '\xc3\xa4\xc3\xb6\xc3\xbc' |
| \end{verbatim} |
| |
| If you have data in a specific encoding and want to produce a |
| corresponding Unicode string from it, you can use the |
| \function{unicode()} function with the encoding name as the second |
| argument. |
| |
| \begin{verbatim} |
| >>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8') |
| u'\xe4\xf6\xfc' |
| \end{verbatim} |
| |
| \subsection{Lists \label{lists}} |
| |
| Python knows a number of \emph{compound} data types, used to group |
| together other values. The most versatile is the \emph{list}, which |
| can be written as a list of comma-separated values (items) between |
| square brackets. List items need not all have the same type. |
| |
| \begin{verbatim} |
| >>> a = ['spam', 'eggs', 100, 1234] |
| >>> a |
| ['spam', 'eggs', 100, 1234] |
| \end{verbatim} |
| |
| Like string indices, list indices start at 0, and lists can be sliced, |
| concatenated and so on: |
| |
| \begin{verbatim} |
| >>> a[0] |
| 'spam' |
| >>> a[3] |
| 1234 |
| >>> a[-2] |
| 100 |
| >>> a[1:-1] |
| ['eggs', 100] |
| >>> a[:2] + ['bacon', 2*2] |
| ['spam', 'eggs', 'bacon', 4] |
| >>> 3*a[:3] + ['Boe!'] |
| ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!'] |
| \end{verbatim} |
| |
| Unlike strings, which are \emph{immutable}, it is possible to change |
| individual elements of a list: |
| |
| \begin{verbatim} |
| >>> a |
| ['spam', 'eggs', 100, 1234] |
| >>> a[2] = a[2] + 23 |
| >>> a |
| ['spam', 'eggs', 123, 1234] |
| \end{verbatim} |
| |
| Assignment to slices is also possible, and this can even change the size |
| of the list: |
| |
| \begin{verbatim} |
| >>> # Replace some items: |
| ... a[0:2] = [1, 12] |
| >>> a |
| [1, 12, 123, 1234] |
| >>> # Remove some: |
| ... a[0:2] = [] |
| >>> a |
| [123, 1234] |
| >>> # Insert some: |
| ... a[1:1] = ['bletch', 'xyzzy'] |
| >>> a |
| [123, 'bletch', 'xyzzy', 1234] |
| >>> a[:0] = a # Insert (a copy of) itself at the beginning |
| >>> a |
| [123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234] |
| \end{verbatim} |
| |
| The built-in function \function{len()} also applies to lists: |
| |
| \begin{verbatim} |
| >>> len(a) |
| 8 |
| \end{verbatim} |
| |
| It is possible to nest lists (create lists containing other lists), |
| for example: |
| |
| \begin{verbatim} |
| >>> q = [2, 3] |
| >>> p = [1, q, 4] |
| >>> len(p) |
| 3 |
| >>> p[1] |
| [2, 3] |
| >>> p[1][0] |
| 2 |
| >>> p[1].append('xtra') # See section 5.1 |
| >>> p |
| [1, [2, 3, 'xtra'], 4] |
| >>> q |
| [2, 3, 'xtra'] |
| \end{verbatim} |
| |
| Note that in the last example, \code{p[1]} and \code{q} really refer to |
| the same object! We'll come back to \emph{object semantics} later. |
| |
| \section{First Steps Towards Programming \label{firstSteps}} |
| |
| Of course, we can use Python for more complicated tasks than adding |
| two and two together. For instance, we can write an initial |
| sub-sequence of the \emph{Fibonacci} series as follows: |
| |
| \begin{verbatim} |
| >>> # Fibonacci series: |
| ... # the sum of two elements defines the next |
| ... a, b = 0, 1 |
| >>> while b < 10: |
| ... print b |
| ... a, b = b, a+b |
| ... |
| 1 |
| 1 |
| 2 |
| 3 |
| 5 |
| 8 |
| \end{verbatim} |
| |
| This example introduces several new features. |
| |
| \begin{itemize} |
| |
| \item |
| The first line contains a \emph{multiple assignment}: the variables |
| \code{a} and \code{b} simultaneously get the new values 0 and 1. On the |
| last line this is used again, demonstrating that the expressions on |
| the right-hand side are all evaluated first before any of the |
| assignments take place. The right-hand side expressions are evaluated |
| from the left to the right. |
| |
| \item |
| The \keyword{while} loop executes as long as the condition (here: |
| \code{b < 10}) remains true. In Python, like in C, any non-zero |
| integer value is true; zero is false. The condition may also be a |
| string or list value, in fact any sequence; anything with a non-zero |
| length is true, empty sequences are false. The test used in the |
| example is a simple comparison. The standard comparison operators are |
| written the same as in C: \code{<} (less than), \code{>} (greater than), |
| \code{==} (equal to), \code{<=} (less than or equal to), |
| \code{>=} (greater than or equal to) and \code{!=} (not equal to). |
| |
| \item |
| The \emph{body} of the loop is \emph{indented}: indentation is Python's |
| way of grouping statements. Python does not (yet!) provide an |
| intelligent input line editing facility, so you have to type a tab or |
| space(s) for each indented line. In practice you will prepare more |
| complicated input for Python with a text editor; most text editors have |
| an auto-indent facility. When a compound statement is entered |
| interactively, it must be followed by a blank line to indicate |
| completion (since the parser cannot guess when you have typed the last |
| line). Note that each line within a basic block must be indented by |
| the same amount. |
| |
| \item |
| The \keyword{print} statement writes the value of the expression(s) it is |
| given. It differs from just writing the expression you want to write |
| (as we did earlier in the calculator examples) in the way it handles |
| multiple expressions and strings. Strings are printed without quotes, |
| and a space is inserted between items, so you can format things nicely, |
| like this: |
| |
| \begin{verbatim} |
| >>> i = 256*256 |
| >>> print 'The value of i is', i |
| The value of i is 65536 |
| \end{verbatim} |
| |
| A trailing comma avoids the newline after the output: |
| |
| \begin{verbatim} |
| >>> a, b = 0, 1 |
| >>> while b < 1000: |
| ... print b, |
| ... a, b = b, a+b |
| ... |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
| \end{verbatim} |
| |
| Note that the interpreter inserts a newline before it prints the next |
| prompt if the last line was not completed. |
| |
| \end{itemize} |
| |
| |
| \chapter{More Control Flow Tools \label{moreControl}} |
| |
| Besides the \keyword{while} statement just introduced, Python knows |
| the usual control flow statements known from other languages, with |
| some twists. |
| |
| \section{\keyword{if} Statements \label{if}} |
| |
| Perhaps the most well-known statement type is the |
| \keyword{if} statement. For example: |
| |
| \begin{verbatim} |
| >>> x = int(raw_input("Please enter an integer: ")) |
| >>> if x < 0: |
| ... x = 0 |
| ... print 'Negative changed to zero' |
| ... elif x == 0: |
| ... print 'Zero' |
| ... elif x == 1: |
| ... print 'Single' |
| ... else: |
| ... print 'More' |
| ... |
| \end{verbatim} |
| |
| There can be zero or more \keyword{elif} parts, and the |
| \keyword{else} part is optional. The keyword `\keyword{elif}' is |
| short for `else if', and is useful to avoid excessive indentation. An |
| \keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence |
| % Weird spacings happen here if the wrapping of the source text |
| % gets changed in the wrong way. |
| is a substitute for the \keyword{switch} or |
| \keyword{case} statements found in other languages. |
| |
| |
| \section{\keyword{for} Statements \label{for}} |
| |
| The \keyword{for}\stindex{for} statement in Python differs a bit from |
| what you may be used to in C or Pascal. Rather than always |
| iterating over an arithmetic progression of numbers (like in Pascal), |
| or giving the user the ability to define both the iteration step and |
| halting condition (as C), Python's |
| \keyword{for}\stindex{for} statement iterates over the items of any |
| sequence (a list or a string), in the order that they appear in |
| the sequence. For example (no pun intended): |
| % One suggestion was to give a real C example here, but that may only |
| % serve to confuse non-C programmers. |
| |
| \begin{verbatim} |
| >>> # Measure some strings: |
| ... a = ['cat', 'window', 'defenestrate'] |
| >>> for x in a: |
| ... print x, len(x) |
| ... |
| cat 3 |
| window 6 |
| defenestrate 12 |
| \end{verbatim} |
| |
| It is not safe to modify the sequence being iterated over in the loop |
| (this can only happen for mutable sequence types, such as lists). If |
| you need to modify the list you are iterating over (for example, to |
| duplicate selected items) you must iterate over a copy. The slice |
| notation makes this particularly convenient: |
| |
| \begin{verbatim} |
| >>> for x in a[:]: # make a slice copy of the entire list |
| ... if len(x) > 6: a.insert(0, x) |
| ... |
| >>> a |
| ['defenestrate', 'cat', 'window', 'defenestrate'] |
| \end{verbatim} |
| |
| |
| \section{The \function{range()} Function \label{range}} |
| |
| If you do need to iterate over a sequence of numbers, the built-in |
| function \function{range()} comes in handy. It generates lists |
| containing arithmetic progressions: |
| |
| \begin{verbatim} |
| >>> range(10) |
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
| \end{verbatim} |
| |
| The given end point is never part of the generated list; |
| \code{range(10)} generates a list of 10 values, exactly the legal |
| indices for items of a sequence of length 10. It is possible to let |
| the range start at another number, or to specify a different increment |
| (even negative; sometimes this is called the `step'): |
| |
| \begin{verbatim} |
| >>> range(5, 10) |
| [5, 6, 7, 8, 9] |
| >>> range(0, 10, 3) |
| [0, 3, 6, 9] |
| >>> range(-10, -100, -30) |
| [-10, -40, -70] |
| \end{verbatim} |
| |
| To iterate over the indices of a sequence, combine |
| \function{range()} and \function{len()} as follows: |
| |
| \begin{verbatim} |
| >>> a = ['Mary', 'had', 'a', 'little', 'lamb'] |
| >>> for i in range(len(a)): |
| ... print i, a[i] |
| ... |
| 0 Mary |
| 1 had |
| 2 a |
| 3 little |
| 4 lamb |
| \end{verbatim} |
| |
| |
| \section{\keyword{break} and \keyword{continue} Statements, and |
| \keyword{else} Clauses on Loops |
| \label{break}} |
| |
| The \keyword{break} statement, like in C, breaks out of the smallest |
| enclosing \keyword{for} or \keyword{while} loop. |
| |
| The \keyword{continue} statement, also borrowed from C, continues |
| with the next iteration of the loop. |
| |
| Loop statements may have an \code{else} clause; it is executed when |
| the loop terminates through exhaustion of the list (with |
| \keyword{for}) or when the condition becomes false (with |
| \keyword{while}), but not when the loop is terminated by a |
| \keyword{break} statement. This is exemplified by the following loop, |
| which searches for prime numbers: |
| |
| \begin{verbatim} |
| >>> for n in range(2, 10): |
| ... for x in range(2, n): |
| ... if n % x == 0: |
| ... print n, 'equals', x, '*', n/x |
| ... break |
| ... else: |
| ... # loop fell through without finding a factor |
| ... print n, 'is a prime number' |
| ... |
| 2 is a prime number |
| 3 is a prime number |
| 4 equals 2 * 2 |
| 5 is a prime number |
| 6 equals 2 * 3 |
| 7 is a prime number |
| 8 equals 2 * 4 |
| 9 equals 3 * 3 |
| \end{verbatim} |
| |
| |
| \section{\keyword{pass} Statements \label{pass}} |
| |
| The \keyword{pass} statement does nothing. |
| It can be used when a statement is required syntactically but the |
| program requires no action. |
| For example: |
| |
| \begin{verbatim} |
| >>> while 1: |
| ... pass # Busy-wait for keyboard interrupt |
| ... |
| \end{verbatim} |
| |
| |
| \section{Defining Functions \label{functions}} |
| |
| We can create a function that writes the Fibonacci series to an |
| arbitrary boundary: |
| |
| \begin{verbatim} |
| >>> def fib(n): # write Fibonacci series up to n |
| ... """Print a Fibonacci series up to n.""" |
| ... a, b = 0, 1 |
| ... while b < n: |
| ... print b, |
| ... a, b = b, a+b |
| ... |
| >>> # Now call the function we just defined: |
| ... fib(2000) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 |
| \end{verbatim} |
| |
| The keyword \keyword{def} introduces a function \emph{definition}. It |
| must be followed by the function name and the parenthesized list of |
| formal parameters. The statements that form the body of the function |
| start at the next line, and must be indented. The first statement of |
| the function body can optionally be a string literal; this string |
| literal is the function's \index{documentation strings}documentation |
| string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation} |
| |
| There are tools which use docstrings to automatically produce online |
| or printed documentation, or to let the user interactively browse |
| through code; it's good practice to include docstrings in code that |
| you write, so try to make a habit of it. |
| |
| The \emph{execution} of a function introduces a new symbol table used |
| for the local variables of the function. More precisely, all variable |
| assignments in a function store the value in the local symbol table; |
| whereas variable references first look in the local symbol table, then |
| in the global symbol table, and then in the table of built-in names. |
| Thus, global variables cannot be directly assigned a value within a |
| function (unless named in a \keyword{global} statement), although |
| they may be referenced. |
| |
| The actual parameters (arguments) to a function call are introduced in |
| the local symbol table of the called function when it is called; thus, |
| arguments are passed using \emph{call by value} (where the |
| \emph{value} is always an object \emph{reference}, not the value of |
| the object).\footnote{ |
| Actually, \emph{call by object reference} would be a better |
| description, since if a mutable object is passed, the caller |
| will see any changes the callee makes to it (items |
| inserted into a list). |
| } When a function calls another function, a new local symbol table is |
| created for that call. |
| |
| A function definition introduces the function name in the current |
| symbol table. The value of the function name |
| has a type that is recognized by the interpreter as a user-defined |
| function. This value can be assigned to another name which can then |
| also be used as a function. This serves as a general renaming |
| mechanism: |
| |
| \begin{verbatim} |
| >>> fib |
| <function object at 10042ed0> |
| >>> f = fib |
| >>> f(100) |
| 1 1 2 3 5 8 13 21 34 55 89 |
| \end{verbatim} |
| |
| You might object that \code{fib} is not a function but a procedure. In |
| Python, like in C, procedures are just functions that don't return a |
| value. In fact, technically speaking, procedures do return a value, |
| albeit a rather boring one. This value is called \code{None} (it's a |
| built-in name). Writing the value \code{None} is normally suppressed by |
| the interpreter if it would be the only value written. You can see it |
| if you really want to: |
| |
| \begin{verbatim} |
| >>> print fib(0) |
| None |
| \end{verbatim} |
| |
| It is simple to write a function that returns a list of the numbers of |
| the Fibonacci series, instead of printing it: |
| |
| \begin{verbatim} |
| >>> def fib2(n): # return Fibonacci series up to n |
| ... """Return a list containing the Fibonacci series up to n.""" |
| ... result = [] |
| ... a, b = 0, 1 |
| ... while b < n: |
| ... result.append(b) # see below |
| ... a, b = b, a+b |
| ... return result |
| ... |
| >>> f100 = fib2(100) # call it |
| >>> f100 # write the result |
| [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
| \end{verbatim} |
| |
| This example, as usual, demonstrates some new Python features: |
| |
| \begin{itemize} |
| |
| \item |
| The \keyword{return} statement returns with a value from a function. |
| \keyword{return} without an expression argument returns \code{None}. |
| Falling off the end of a procedure also returns \code{None}. |
| |
| \item |
| The statement \code{result.append(b)} calls a \emph{method} of the list |
| object \code{result}. A method is a function that `belongs' to an |
| object and is named \code{obj.methodname}, where \code{obj} is some |
| object (this may be an expression), and \code{methodname} is the name |
| of a method that is defined by the object's type. Different types |
| define different methods. Methods of different types may have the |
| same name without causing ambiguity. (It is possible to define your |
| own object types and methods, using \emph{classes}, as discussed later |
| in this tutorial.) |
| The method \method{append()} shown in the example, is defined for |
| list objects; it adds a new element at the end of the list. In this |
| example it is equivalent to \samp{result = result + [b]}, but more |
| efficient. |
| |
| \end{itemize} |
| |
| \section{More on Defining Functions \label{defining}} |
| |
| It is also possible to define functions with a variable number of |
| arguments. There are three forms, which can be combined. |
| |
| \subsection{Default Argument Values \label{defaultArgs}} |
| |
| The most useful form is to specify a default value for one or more |
| arguments. This creates a function that can be called with fewer |
| arguments than it is defined |
| |
| \begin{verbatim} |
| def ask_ok(prompt, retries=4, complaint='Yes or no, please!'): |
| while 1: |
| ok = raw_input(prompt) |
| if ok in ('y', 'ye', 'yes'): return 1 |
| if ok in ('n', 'no', 'nop', 'nope'): return 0 |
| retries = retries - 1 |
| if retries < 0: raise IOError, 'refusenik user' |
| print complaint |
| \end{verbatim} |
| |
| This function can be called either like this: |
| \code{ask_ok('Do you really want to quit?')} or like this: |
| \code{ask_ok('OK to overwrite the file?', 2)}. |
| |
| The default values are evaluated at the point of function definition |
| in the \emph{defining} scope, so that |
| |
| \begin{verbatim} |
| i = 5 |
| |
| def f(arg=i): |
| print arg |
| |
| i = 6 |
| f() |
| \end{verbatim} |
| |
| will print \code{5}. |
| |
| \strong{Important warning:} The default value is evaluated only once. |
| This makes a difference when the default is a mutable object such as a |
| list or dictionary. For example, the following function accumulates |
| the arguments passed to it on subsequent calls: |
| |
| \begin{verbatim} |
| def f(a, L=[]): |
| L.append(a) |
| return L |
| |
| print f(1) |
| print f(2) |
| print f(3) |
| \end{verbatim} |
| |
| This will print |
| |
| \begin{verbatim} |
| [1] |
| [1, 2] |
| [1, 2, 3] |
| \end{verbatim} |
| |
| If you don't want the default to be shared between subsequent calls, |
| you can write the function like this instead: |
| |
| \begin{verbatim} |
| def f(a, L=None): |
| if L is None: |
| L = [] |
| L.append(a) |
| return L |
| \end{verbatim} |
| |
| \subsection{Keyword Arguments \label{keywordArgs}} |
| |
| Functions can also be called using |
| keyword arguments of the form \samp{\var{keyword} = \var{value}}. For |
| instance, the following function: |
| |
| \begin{verbatim} |
| def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'): |
| print "-- This parrot wouldn't", action, |
| print "if you put", voltage, "Volts through it." |
| print "-- Lovely plumage, the", type |
| print "-- It's", state, "!" |
| \end{verbatim} |
| |
| could be called in any of the following ways: |
| |
| \begin{verbatim} |
| parrot(1000) |
| parrot(action = 'VOOOOOM', voltage = 1000000) |
| parrot('a thousand', state = 'pushing up the daisies') |
| parrot('a million', 'bereft of life', 'jump') |
| \end{verbatim} |
| |
| but the following calls would all be invalid: |
| |
| \begin{verbatim} |
| parrot() # required argument missing |
| parrot(voltage=5.0, 'dead') # non-keyword argument following keyword |
| parrot(110, voltage=220) # duplicate value for argument |
| parrot(actor='John Cleese') # unknown keyword |
| \end{verbatim} |
| |
| In general, an argument list must have any positional arguments |
| followed by any keyword arguments, where the keywords must be chosen |
| from the formal parameter names. It's not important whether a formal |
| parameter has a default value or not. No argument may receive a |
| value more than once --- formal parameter names corresponding to |
| positional arguments cannot be used as keywords in the same calls. |
| Here's an example that fails due to this restriction: |
| |
| \begin{verbatim} |
| >>> def function(a): |
| ... pass |
| ... |
| >>> function(0, a=0) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: keyword parameter redefined |
| \end{verbatim} |
| |
| When a final formal parameter of the form \code{**\var{name}} is |
| present, it receives a dictionary containing all keyword arguments |
| whose keyword doesn't correspond to a formal parameter. This may be |
| combined with a formal parameter of the form |
| \code{*\var{name}} (described in the next subsection) which receives a |
| tuple containing the positional arguments beyond the formal parameter |
| list. (\code{*\var{name}} must occur before \code{**\var{name}}.) |
| For example, if we define a function like this: |
| |
| \begin{verbatim} |
| def cheeseshop(kind, *arguments, **keywords): |
| print "-- Do you have any", kind, '?' |
| print "-- I'm sorry, we're all out of", kind |
| for arg in arguments: print arg |
| print '-'*40 |
| keys = keywords.keys() |
| keys.sort() |
| for kw in keys: print kw, ':', keywords[kw] |
| \end{verbatim} |
| |
| It could be called like this: |
| |
| \begin{verbatim} |
| cheeseshop('Limburger', "It's very runny, sir.", |
| "It's really very, VERY runny, sir.", |
| client='John Cleese', |
| shopkeeper='Michael Palin', |
| sketch='Cheese Shop Sketch') |
| \end{verbatim} |
| |
| and of course it would print: |
| |
| \begin{verbatim} |
| -- Do you have any Limburger ? |
| -- I'm sorry, we're all out of Limburger |
| It's very runny, sir. |
| It's really very, VERY runny, sir. |
| ---------------------------------------- |
| client : John Cleese |
| shopkeeper : Michael Palin |
| sketch : Cheese Shop Sketch |
| \end{verbatim} |
| |
| Note that the \method{sort()} method of the list of keyword argument |
| names is called before printing the contents of the \code{keywords} |
| dictionary; if this is not done, the order in which the arguments are |
| printed is undefined. |
| |
| |
| \subsection{Arbitrary Argument Lists \label{arbitraryArgs}} |
| |
| Finally, the least frequently used option is to specify that a |
| function can be called with an arbitrary number of arguments. These |
| arguments will be wrapped up in a tuple. Before the variable number |
| of arguments, zero or more normal arguments may occur. |
| |
| \begin{verbatim} |
| def fprintf(file, format, *args): |
| file.write(format % args) |
| \end{verbatim} |
| |
| |
| \subsection{Lambda Forms \label{lambda}} |
| |
| By popular demand, a few features commonly found in functional |
| programming languages and Lisp have been added to Python. With the |
| \keyword{lambda} keyword, small anonymous functions can be created. |
| Here's a function that returns the sum of its two arguments: |
| \samp{lambda a, b: a+b}. Lambda forms can be used wherever function |
| objects are required. They are syntactically restricted to a single |
| expression. Semantically, they are just syntactic sugar for a normal |
| function definition. Like nested function definitions, lambda forms |
| can reference variables from the containing scope: |
| |
| \begin{verbatim} |
| >>> def make_incrementor(n): |
| ... return lambda x: x + n |
| ... |
| >>> f = make_incrementor(42) |
| >>> f(0) |
| 42 |
| >>> f(1) |
| 43 |
| \end{verbatim} |
| |
| |
| \subsection{Documentation Strings \label{docstrings}} |
| |
| There are emerging conventions about the content and formatting of |
| documentation strings. |
| \index{docstrings}\index{documentation strings} |
| \index{strings, documentation} |
| |
| The first line should always be a short, concise summary of the |
| object's purpose. For brevity, it should not explicitly state the |
| object's name or type, since these are available by other means |
| (except if the name happens to be a verb describing a function's |
| operation). This line should begin with a capital letter and end with |
| a period. |
| |
| If there are more lines in the documentation string, the second line |
| should be blank, visually separating the summary from the rest of the |
| description. The following lines should be one or more paragraphs |
| describing the object's calling conventions, its side effects, etc. |
| |
| The Python parser does not strip indentation from multi-line string |
| literals in Python, so tools that process documentation have to strip |
| indentation if desired. This is done using the following convention. |
| The first non-blank line \emph{after} the first line of the string |
| determines the amount of indentation for the entire documentation |
| string. (We can't use the first line since it is generally adjacent |
| to the string's opening quotes so its indentation is not apparent in |
| the string literal.) Whitespace ``equivalent'' to this indentation is |
| then stripped from the start of all lines of the string. Lines that |
| are indented less should not occur, but if they occur all their |
| leading whitespace should be stripped. Equivalence of whitespace |
| should be tested after expansion of tabs (to 8 spaces, normally). |
| |
| Here is an example of a multi-line docstring: |
| |
| \begin{verbatim} |
| >>> def my_function(): |
| ... """Do nothing, but document it. |
| ... |
| ... No, really, it doesn't do anything. |
| ... """ |
| ... pass |
| ... |
| >>> print my_function.__doc__ |
| Do nothing, but document it. |
| |
| No, really, it doesn't do anything. |
| |
| \end{verbatim} |
| |
| |
| |
| \chapter{Data Structures \label{structures}} |
| |
| This chapter describes some things you've learned about already in |
| more detail, and adds some new things as well. |
| |
| |
| \section{More on Lists \label{moreLists}} |
| |
| The list data type has some more methods. Here are all of the methods |
| of list objects: |
| |
| \begin{description} |
| |
| \item[\code{append(x)}] |
| Add an item to the end of the list; |
| equivalent to \code{a[len(a):] = [x]}. |
| |
| \item[\code{extend(L)}] |
| Extend the list by appending all the items in the given list; |
| equivalent to \code{a[len(a):] = L}. |
| |
| \item[\code{insert(i, x)}] |
| Insert an item at a given position. The first argument is the index of |
| the element before which to insert, so \code{a.insert(0, x)} inserts at |
| the front of the list, and \code{a.insert(len(a), x)} is equivalent to |
| \code{a.append(x)}. |
| |
| \item[\code{remove(x)}] |
| Remove the first item from the list whose value is \code{x}. |
| It is an error if there is no such item. |
| |
| \item[\code{pop(\optional{i})}] |
| Remove the item at the given position in the list, and return it. If |
| no index is specified, \code{a.pop()} returns the last item in the |
| list. The item is also removed from the list. |
| |
| \item[\code{index(x)}] |
| Return the index in the list of the first item whose value is \code{x}. |
| It is an error if there is no such item. |
| |
| \item[\code{count(x)}] |
| Return the number of times \code{x} appears in the list. |
| |
| \item[\code{sort()}] |
| Sort the items of the list, in place. |
| |
| \item[\code{reverse()}] |
| Reverse the elements of the list, in place. |
| |
| \end{description} |
| |
| An example that uses most of the list methods: |
| |
| \begin{verbatim} |
| >>> a = [66.6, 333, 333, 1, 1234.5] |
| >>> print a.count(333), a.count(66.6), a.count('x') |
| 2 1 0 |
| >>> a.insert(2, -1) |
| >>> a.append(333) |
| >>> a |
| [66.6, 333, -1, 333, 1, 1234.5, 333] |
| >>> a.index(333) |
| 1 |
| >>> a.remove(333) |
| >>> a |
| [66.6, -1, 333, 1, 1234.5, 333] |
| >>> a.reverse() |
| >>> a |
| [333, 1234.5, 1, 333, -1, 66.6] |
| >>> a.sort() |
| >>> a |
| [-1, 1, 66.6, 333, 333, 1234.5] |
| \end{verbatim} |
| |
| |
| \subsection{Using Lists as Stacks \label{lists-as-stacks}} |
| \sectionauthor{Ka-Ping Yee}{ping@lfw.org} |
| |
| The list methods make it very easy to use a list as a stack, where the |
| last element added is the first element retrieved (``last-in, |
| first-out''). To add an item to the top of the stack, use |
| \method{append()}. To retrieve an item from the top of the stack, use |
| \method{pop()} without an explicit index. For example: |
| |
| \begin{verbatim} |
| >>> stack = [3, 4, 5] |
| >>> stack.append(6) |
| >>> stack.append(7) |
| >>> stack |
| [3, 4, 5, 6, 7] |
| >>> stack.pop() |
| 7 |
| >>> stack |
| [3, 4, 5, 6] |
| >>> stack.pop() |
| 6 |
| >>> stack.pop() |
| 5 |
| >>> stack |
| [3, 4] |
| \end{verbatim} |
| |
| |
| \subsection{Using Lists as Queues \label{lists-as-queues}} |
| \sectionauthor{Ka-Ping Yee}{ping@lfw.org} |
| |
| You can also use a list conveniently as a queue, where the first |
| element added is the first element retrieved (``first-in, |
| first-out''). To add an item to the back of the queue, use |
| \method{append()}. To retrieve an item from the front of the queue, |
| use \method{pop()} with \code{0} as the index. For example: |
| |
| \begin{verbatim} |
| >>> queue = ["Eric", "John", "Michael"] |
| >>> queue.append("Terry") # Terry arrives |
| >>> queue.append("Graham") # Graham arrives |
| >>> queue.pop(0) |
| 'Eric' |
| >>> queue.pop(0) |
| 'John' |
| >>> queue |
| ['Michael', 'Terry', 'Graham'] |
| \end{verbatim} |
| |
| |
| \subsection{Functional Programming Tools \label{functional}} |
| |
| There are three built-in functions that are very useful when used with |
| lists: \function{filter()}, \function{map()}, and \function{reduce()}. |
| |
| \samp{filter(\var{function}, \var{sequence})} returns a sequence (of |
| the same type, if possible) consisting of those items from the |
| sequence for which \code{\var{function}(\var{item})} is true. For |
| example, to compute some primes: |
| |
| \begin{verbatim} |
| >>> def f(x): return x % 2 != 0 and x % 3 != 0 |
| ... |
| >>> filter(f, range(2, 25)) |
| [5, 7, 11, 13, 17, 19, 23] |
| \end{verbatim} |
| |
| \samp{map(\var{function}, \var{sequence})} calls |
| \code{\var{function}(\var{item})} for each of the sequence's items and |
| returns a list of the return values. For example, to compute some |
| cubes: |
| |
| \begin{verbatim} |
| >>> def cube(x): return x*x*x |
| ... |
| >>> map(cube, range(1, 11)) |
| [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000] |
| \end{verbatim} |
| |
| More than one sequence may be passed; the function must then have as |
| many arguments as there are sequences and is called with the |
| corresponding item from each sequence (or \code{None} if some sequence |
| is shorter than another). If \code{None} is passed for the function, |
| a function returning its argument(s) is substituted. |
| |
| Combining these two special cases, we see that |
| \samp{map(None, \var{list1}, \var{list2})} is a convenient way of |
| turning a pair of lists into a list of pairs. For example: |
| |
| \begin{verbatim} |
| >>> seq = range(8) |
| >>> def square(x): return x*x |
| ... |
| >>> map(None, seq, map(square, seq)) |
| [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)] |
| \end{verbatim} |
| |
| \samp{reduce(\var{func}, \var{sequence})} returns a single value |
| constructed by calling the binary function \var{func} on the first two |
| items of the sequence, then on the result and the next item, and so |
| on. For example, to compute the sum of the numbers 1 through 10: |
| |
| \begin{verbatim} |
| >>> def add(x,y): return x+y |
| ... |
| >>> reduce(add, range(1, 11)) |
| 55 |
| \end{verbatim} |
| |
| If there's only one item in the sequence, its value is returned; if |
| the sequence is empty, an exception is raised. |
| |
| A third argument can be passed to indicate the starting value. In this |
| case the starting value is returned for an empty sequence, and the |
| function is first applied to the starting value and the first sequence |
| item, then to the result and the next item, and so on. For example, |
| |
| \begin{verbatim} |
| >>> def sum(seq): |
| ... def add(x,y): return x+y |
| ... return reduce(add, seq, 0) |
| ... |
| >>> sum(range(1, 11)) |
| 55 |
| >>> sum([]) |
| 0 |
| \end{verbatim} |
| |
| |
| \subsection{List Comprehensions} |
| |
| List comprehensions provide a concise way to create lists without resorting |
| to use of \function{map()}, \function{filter()} and/or \keyword{lambda}. |
| The resulting list definition tends often to be clearer than lists built |
| using those constructs. Each list comprehension consists of an expression |
| following by a \keyword{for} clause, then zero or more \keyword{for} or |
| \keyword{if} clauses. The result will be a list resulting from evaluating |
| the expression in the context of the \keyword{for} and \keyword{if} clauses |
| which follow it. If the expression would evaluate to a tuple, it must be |
| parenthesized. |
| |
| \begin{verbatim} |
| >>> freshfruit = [' banana', ' loganberry ', 'passion fruit '] |
| >>> [weapon.strip() for weapon in freshfruit] |
| ['banana', 'loganberry', 'passion fruit'] |
| >>> vec = [2, 4, 6] |
| >>> [3*x for x in vec] |
| [6, 12, 18] |
| >>> [3*x for x in vec if x > 3] |
| [12, 18] |
| >>> [3*x for x in vec if x < 2] |
| [] |
| >>> [{x: x**2} for x in vec] |
| [{2: 4}, {4: 16}, {6: 36}] |
| >>> [[x,x**2] for x in vec] |
| [[2, 4], [4, 16], [6, 36]] |
| >>> [x, x**2 for x in vec] # error - parens required for tuples |
| File "<stdin>", line 1, in ? |
| [x, x**2 for x in vec] |
| ^ |
| SyntaxError: invalid syntax |
| >>> [(x, x**2) for x in vec] |
| [(2, 4), (4, 16), (6, 36)] |
| >>> vec1 = [2, 4, 6] |
| >>> vec2 = [4, 3, -9] |
| >>> [x*y for x in vec1 for y in vec2] |
| [8, 6, -18, 16, 12, -36, 24, 18, -54] |
| >>> [x+y for x in vec1 for y in vec2] |
| [6, 5, -7, 8, 7, -5, 10, 9, -3] |
| >>> [vec1[i]*vec2[i] for i in range(len(vec1))] |
| [8, 12, -54] |
| \end{verbatim} |
| |
| |
| \section{The \keyword{del} statement \label{del}} |
| |
| There is a way to remove an item from a list given its index instead |
| of its value: the \keyword{del} statement. This can also be used to |
| remove slices from a list (which we did earlier by assignment of an |
| empty list to the slice). For example: |
| |
| \begin{verbatim} |
| >>> a |
| [-1, 1, 66.6, 333, 333, 1234.5] |
| >>> del a[0] |
| >>> a |
| [1, 66.6, 333, 333, 1234.5] |
| >>> del a[2:4] |
| >>> a |
| [1, 66.6, 1234.5] |
| \end{verbatim} |
| |
| \keyword{del} can also be used to delete entire variables: |
| |
| \begin{verbatim} |
| >>> del a |
| \end{verbatim} |
| |
| Referencing the name \code{a} hereafter is an error (at least until |
| another value is assigned to it). We'll find other uses for |
| \keyword{del} later. |
| |
| |
| \section{Tuples and Sequences \label{tuples}} |
| |
| We saw that lists and strings have many common properties, such as |
| indexing and slicing operations. They are two examples of |
| \emph{sequence} data types. Since Python is an evolving language, |
| other sequence data types may be added. There is also another |
| standard sequence data type: the \emph{tuple}. |
| |
| A tuple consists of a number of values separated by commas, for |
| instance: |
| |
| \begin{verbatim} |
| >>> t = 12345, 54321, 'hello!' |
| >>> t[0] |
| 12345 |
| >>> t |
| (12345, 54321, 'hello!') |
| >>> # Tuples may be nested: |
| ... u = t, (1, 2, 3, 4, 5) |
| >>> u |
| ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5)) |
| \end{verbatim} |
| |
| As you see, on output tuples are alway enclosed in parentheses, so |
| that nested tuples are interpreted correctly; they may be input with |
| or without surrounding parentheses, although often parentheses are |
| necessary anyway (if the tuple is part of a larger expression). |
| |
| Tuples have many uses. For example: (x, y) coordinate pairs, employee |
| records from a database, etc. Tuples, like strings, are immutable: it |
| is not possible to assign to the individual items of a tuple (you can |
| simulate much of the same effect with slicing and concatenation, |
| though). It is also possible to create tuples which contain mutable |
| objects, such as lists. |
| |
| A special problem is the construction of tuples containing 0 or 1 |
| items: the syntax has some extra quirks to accommodate these. Empty |
| tuples are constructed by an empty pair of parentheses; a tuple with |
| one item is constructed by following a value with a comma |
| (it is not sufficient to enclose a single value in parentheses). |
| Ugly, but effective. For example: |
| |
| \begin{verbatim} |
| >>> empty = () |
| >>> singleton = 'hello', # <-- note trailing comma |
| >>> len(empty) |
| 0 |
| >>> len(singleton) |
| 1 |
| >>> singleton |
| ('hello',) |
| \end{verbatim} |
| |
| The statement \code{t = 12345, 54321, 'hello!'} is an example of |
| \emph{tuple packing}: the values \code{12345}, \code{54321} and |
| \code{'hello!'} are packed together in a tuple. The reverse operation |
| is also possible: |
| |
| \begin{verbatim} |
| >>> x, y, z = t |
| \end{verbatim} |
| |
| This is called, appropriately enough, \emph{sequence unpacking}. |
| Sequence unpacking requires that the list of variables on the left |
| have the same number of elements as the length of the sequence. Note |
| that multiple assignment is really just a combination of tuple packing |
| and sequence unpacking! |
| |
| There is a small bit of asymmetry here: packing multiple values |
| always creates a tuple, and unpacking works for any sequence. |
| |
| % XXX Add a bit on the difference between tuples and lists. |
| |
| |
| \section{Dictionaries \label{dictionaries}} |
| |
| Another useful data type built into Python is the \emph{dictionary}. |
| Dictionaries are sometimes found in other languages as ``associative |
| memories'' or ``associative arrays''. Unlike sequences, which are |
| indexed by a range of numbers, dictionaries are indexed by \emph{keys}, |
| which can be any immutable type; strings and numbers can always be |
| keys. Tuples can be used as keys if they contain only strings, |
| numbers, or tuples; if a tuple contains any mutable object either |
| directly or indirectly, it cannot be used as a key. You can't use |
| lists as keys, since lists can be modified in place using their |
| \method{append()} and \method{extend()} methods, as well as slice and |
| indexed assignments. |
| |
| It is best to think of a dictionary as an unordered set of |
| \emph{key: value} pairs, with the requirement that the keys are unique |
| (within one dictionary). |
| A pair of braces creates an empty dictionary: \code{\{\}}. |
| Placing a comma-separated list of key:value pairs within the |
| braces adds initial key:value pairs to the dictionary; this is also the |
| way dictionaries are written on output. |
| |
| The main operations on a dictionary are storing a value with some key |
| and extracting the value given the key. It is also possible to delete |
| a key:value pair |
| with \code{del}. |
| If you store using a key that is already in use, the old value |
| associated with that key is forgotten. It is an error to extract a |
| value using a non-existent key. |
| |
| The \code{keys()} method of a dictionary object returns a list of all |
| the keys used in the dictionary, in random order (if you want it |
| sorted, just apply the \code{sort()} method to the list of keys). To |
| check whether a single key is in the dictionary, use the |
| \code{has_key()} method of the dictionary. |
| |
| Here is a small example using a dictionary: |
| |
| \begin{verbatim} |
| >>> tel = {'jack': 4098, 'sape': 4139} |
| >>> tel['guido'] = 4127 |
| >>> tel |
| {'sape': 4139, 'guido': 4127, 'jack': 4098} |
| >>> tel['jack'] |
| 4098 |
| >>> del tel['sape'] |
| >>> tel['irv'] = 4127 |
| >>> tel |
| {'guido': 4127, 'irv': 4127, 'jack': 4098} |
| >>> tel.keys() |
| ['guido', 'irv', 'jack'] |
| >>> tel.has_key('guido') |
| 1 |
| \end{verbatim} |
| |
| \section{More on Conditions \label{conditions}} |
| |
| The conditions used in \code{while} and \code{if} statements above can |
| contain other operators besides comparisons. |
| |
| The comparison operators \code{in} and \code{not in} check whether a value |
| occurs (does not occur) in a sequence. The operators \code{is} and |
| \code{is not} compare whether two objects are really the same object; this |
| only matters for mutable objects like lists. All comparison operators |
| have the same priority, which is lower than that of all numerical |
| operators. |
| |
| Comparisons can be chained. For example, \code{a < b == c} tests |
| whether \code{a} is less than \code{b} and moreover \code{b} equals |
| \code{c}. |
| |
| Comparisons may be combined by the Boolean operators \code{and} and |
| \code{or}, and the outcome of a comparison (or of any other Boolean |
| expression) may be negated with \code{not}. These all have lower |
| priorities than comparison operators again; between them, \code{not} has |
| the highest priority, and \code{or} the lowest, so that |
| \code{A and not B or C} is equivalent to \code{(A and (not B)) or C}. Of |
| course, parentheses can be used to express the desired composition. |
| |
| The Boolean operators \code{and} and \code{or} are so-called |
| \emph{shortcut} operators: their arguments are evaluated from left to |
| right, and evaluation stops as soon as the outcome is determined. |
| E.g., if \code{A} and \code{C} are true but \code{B} is false, \code{A |
| and B and C} does not evaluate the expression C. In general, the |
| return value of a shortcut operator, when used as a general value and |
| not as a Boolean, is the last evaluated argument. |
| |
| It is possible to assign the result of a comparison or other Boolean |
| expression to a variable. For example, |
| |
| \begin{verbatim} |
| >>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance' |
| >>> non_null = string1 or string2 or string3 |
| >>> non_null |
| 'Trondheim' |
| \end{verbatim} |
| |
| Note that in Python, unlike C, assignment cannot occur inside expressions. |
| C programmers may grumble about this, but it avoids a common class of |
| problems encountered in C programs: typing \code{=} in an expression when |
| \code{==} was intended. |
| |
| |
| \section{Comparing Sequences and Other Types \label{comparing}} |
| |
| Sequence objects may be compared to other objects with the same |
| sequence type. The comparison uses \emph{lexicographical} ordering: |
| first the first two items are compared, and if they differ this |
| determines the outcome of the comparison; if they are equal, the next |
| two items are compared, and so on, until either sequence is exhausted. |
| If two items to be compared are themselves sequences of the same type, |
| the lexicographical comparison is carried out recursively. If all |
| items of two sequences compare equal, the sequences are considered |
| equal. If one sequence is an initial sub-sequence of the other, the |
| shorter sequence is the smaller (lesser) one. Lexicographical |
| ordering for strings uses the \ASCII{} ordering for individual |
| characters. Some examples of comparisons between sequences with the |
| same types: |
| |
| \begin{verbatim} |
| (1, 2, 3) < (1, 2, 4) |
| [1, 2, 3] < [1, 2, 4] |
| 'ABC' < 'C' < 'Pascal' < 'Python' |
| (1, 2, 3, 4) < (1, 2, 4) |
| (1, 2) < (1, 2, -1) |
| (1, 2, 3) == (1.0, 2.0, 3.0) |
| (1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4) |
| \end{verbatim} |
| |
| Note that comparing objects of different types is legal. The outcome |
| is deterministic but arbitrary: the types are ordered by their name. |
| Thus, a list is always smaller than a string, a string is always |
| smaller than a tuple, etc. Mixed numeric types are compared according |
| to their numeric value, so 0 equals 0.0, etc.\footnote{ |
| The rules for comparing objects of different types should |
| not be relied upon; they may change in a future version of |
| the language. |
| } |
| |
| |
| \chapter{Modules \label{modules}} |
| |
| If you quit from the Python interpreter and enter it again, the |
| definitions you have made (functions and variables) are lost. |
| Therefore, if you want to write a somewhat longer program, you are |
| better off using a text editor to prepare the input for the interpreter |
| and running it with that file as input instead. This is known as creating a |
| \emph{script}. As your program gets longer, you may want to split it |
| into several files for easier maintenance. You may also want to use a |
| handy function that you've written in several programs without copying |
| its definition into each program. |
| |
| To support this, Python has a way to put definitions in a file and use |
| them in a script or in an interactive instance of the interpreter. |
| Such a file is called a \emph{module}; definitions from a module can be |
| \emph{imported} into other modules or into the \emph{main} module (the |
| collection of variables that you have access to in a script |
| executed at the top level |
| and in calculator mode). |
| |
| A module is a file containing Python definitions and statements. The |
| file name is the module name with the suffix \file{.py} appended. Within |
| a module, the module's name (as a string) is available as the value of |
| the global variable \code{__name__}. For instance, use your favorite text |
| editor to create a file called \file{fibo.py} in the current directory |
| with the following contents: |
| |
| \begin{verbatim} |
| # Fibonacci numbers module |
| |
| def fib(n): # write Fibonacci series up to n |
| a, b = 0, 1 |
| while b < n: |
| print b, |
| a, b = b, a+b |
| |
| def fib2(n): # return Fibonacci series up to n |
| result = [] |
| a, b = 0, 1 |
| while b < n: |
| result.append(b) |
| a, b = b, a+b |
| return result |
| \end{verbatim} |
| |
| Now enter the Python interpreter and import this module with the |
| following command: |
| |
| \begin{verbatim} |
| >>> import fibo |
| \end{verbatim} |
| |
| This does not enter the names of the functions defined in \code{fibo} |
| directly in the current symbol table; it only enters the module name |
| \code{fibo} there. |
| Using the module name you can access the functions: |
| |
| \begin{verbatim} |
| >>> fibo.fib(1000) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 |
| >>> fibo.fib2(100) |
| [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] |
| >>> fibo.__name__ |
| 'fibo' |
| \end{verbatim} |
| |
| If you intend to use a function often you can assign it to a local name: |
| |
| \begin{verbatim} |
| >>> fib = fibo.fib |
| >>> fib(500) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| \end{verbatim} |
| |
| |
| \section{More on Modules \label{moreModules}} |
| |
| A module can contain executable statements as well as function |
| definitions. |
| These statements are intended to initialize the module. |
| They are executed only the |
| \emph{first} time the module is imported somewhere.\footnote{ |
| In fact function definitions are also `statements' that are |
| `executed'; the execution enters the function name in the |
| module's global symbol table. |
| } |
| |
| Each module has its own private symbol table, which is used as the |
| global symbol table by all functions defined in the module. |
| Thus, the author of a module can use global variables in the module |
| without worrying about accidental clashes with a user's global |
| variables. |
| On the other hand, if you know what you are doing you can touch a |
| module's global variables with the same notation used to refer to its |
| functions, |
| \code{modname.itemname}. |
| |
| Modules can import other modules. It is customary but not required to |
| place all \keyword{import} statements at the beginning of a module (or |
| script, for that matter). The imported module names are placed in the |
| importing module's global symbol table. |
| |
| There is a variant of the \keyword{import} statement that imports |
| names from a module directly into the importing module's symbol |
| table. For example: |
| |
| \begin{verbatim} |
| >>> from fibo import fib, fib2 |
| >>> fib(500) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| \end{verbatim} |
| |
| This does not introduce the module name from which the imports are taken |
| in the local symbol table (so in the example, \code{fibo} is not |
| defined). |
| |
| There is even a variant to import all names that a module defines: |
| |
| \begin{verbatim} |
| >>> from fibo import * |
| >>> fib(500) |
| 1 1 2 3 5 8 13 21 34 55 89 144 233 377 |
| \end{verbatim} |
| |
| This imports all names except those beginning with an underscore |
| (\code{_}). |
| |
| |
| \subsection{The Module Search Path \label{searchPath}} |
| |
| \indexiii{module}{search}{path} |
| When a module named \module{spam} is imported, the interpreter searches |
| for a file named \file{spam.py} in the current directory, |
| and then in the list of directories specified by |
| the environment variable \envvar{PYTHONPATH}. This has the same syntax as |
| the shell variable \envvar{PATH}, that is, a list of |
| directory names. When \envvar{PYTHONPATH} is not set, or when the file |
| is not found there, the search continues in an installation-dependent |
| default path; on \UNIX, this is usually \file{.:/usr/local/lib/python}. |
| |
| Actually, modules are searched in the list of directories given by the |
| variable \code{sys.path} which is initialized from the directory |
| containing the input script (or the current directory), |
| \envvar{PYTHONPATH} and the installation-dependent default. This allows |
| Python programs that know what they're doing to modify or replace the |
| module search path. Note that because the directory containing the |
| script being run is on the search path, it is important that the |
| script not have the same name as a standard module, or Python will |
| attempt to load the script as a module when that module is imported. |
| This will generally be an error. See section~\ref{standardModules}, |
| ``Standard Modules.'' for more information. |
| |
| |
| \subsection{``Compiled'' Python files} |
| |
| As an important speed-up of the start-up time for short programs that |
| use a lot of standard modules, if a file called \file{spam.pyc} exists |
| in the directory where \file{spam.py} is found, this is assumed to |
| contain an already-``byte-compiled'' version of the module \module{spam}. |
| The modification time of the version of \file{spam.py} used to create |
| \file{spam.pyc} is recorded in \file{spam.pyc}, and the |
| \file{.pyc} file is ignored if these don't match. |
| |
| Normally, you don't need to do anything to create the |
| \file{spam.pyc} file. Whenever \file{spam.py} is successfully |
| compiled, an attempt is made to write the compiled version to |
| \file{spam.pyc}. It is not an error if this attempt fails; if for any |
| reason the file is not written completely, the resulting |
| \file{spam.pyc} file will be recognized as invalid and thus ignored |
| later. The contents of the \file{spam.pyc} file are platform |
| independent, so a Python module directory can be shared by machines of |
| different architectures. |
| |
| Some tips for experts: |
| |
| \begin{itemize} |
| |
| \item |
| When the Python interpreter is invoked with the \programopt{-O} flag, |
| optimized code is generated and stored in \file{.pyo} files. |
| The optimizer currently doesn't help much; it only removes |
| \keyword{assert} statements and \code{SET_LINENO} instructions. |
| When \programopt{-O} is used, \emph{all} bytecode is optimized; |
| \code{.pyc} files are ignored and \code{.py} files are compiled to |
| optimized bytecode. |
| |
| \item |
| Passing two \programopt{-O} flags to the Python interpreter |
| (\programopt{-OO}) will cause the bytecode compiler to perform |
| optimizations that could in some rare cases result in malfunctioning |
| programs. Currently only \code{__doc__} strings are removed from the |
| bytecode, resulting in more compact \file{.pyo} files. Since some |
| programs may rely on having these available, you should only use this |
| option if you know what you're doing. |
| |
| \item |
| A program doesn't run any faster when it is read from a \file{.pyc} or |
| \file{.pyo} file than when it is read from a \file{.py} file; the only |
| thing that's faster about \file{.pyc} or \file{.pyo} files is the |
| speed with which they are loaded. |
| |
| \item |
| When a script is run by giving its name on the command line, the |
| bytecode for the script is never written to a \file{.pyc} or |
| \file{.pyo} file. Thus, the startup time of a script may be reduced |
| by moving most of its code to a module and having a small bootstrap |
| script that imports that module. It is also possible to name a |
| \file{.pyc} or \file{.pyo} file directly on the command line. |
| |
| \item |
| It is possible to have a file called \file{spam.pyc} (or |
| \file{spam.pyo} when \programopt{-O} is used) without a file |
| \file{spam.py} for the same module. This can be used to distribute a |
| library of Python code in a form that is moderately hard to reverse |
| engineer. |
| |
| \item |
| The module \module{compileall}\refstmodindex{compileall} can create |
| \file{.pyc} files (or \file{.pyo} files when \programopt{-O} is used) for |
| all modules in a directory. |
| |
| \end{itemize} |
| |
| |
| \section{Standard Modules \label{standardModules}} |
| |
| Python comes with a library of standard modules, described in a separate |
| document, the \citetitle[../lib/lib.html]{Python Library Reference} |
| (``Library Reference'' hereafter). Some modules are built into the |
| interpreter; these provide access to operations that are not part of |
| the core of the language but are nevertheless built in, either for |
| efficiency or to provide access to operating system primitives such as |
| system calls. The set of such modules is a configuration option which |
| also dependson the underlying platform For example, |
| the \module{amoeba} module is only provided on systems that somehow |
| support Amoeba primitives. One particular module deserves some |
| attention: \module{sys}\refstmodindex{sys}, which is built into every |
| Python interpreter. The variables \code{sys.ps1} and |
| \code{sys.ps2} define the strings used as primary and secondary |
| prompts: |
| |
| \begin{verbatim} |
| >>> import sys |
| >>> sys.ps1 |
| '>>> ' |
| >>> sys.ps2 |
| '... ' |
| >>> sys.ps1 = 'C> ' |
| C> print 'Yuck!' |
| Yuck! |
| C> |
| \end{verbatim} |
| |
| These two variables are only defined if the interpreter is in |
| interactive mode. |
| |
| The variable \code{sys.path} is a list of strings that determine the |
| interpreter's search path for modules. It is initialized to a default |
| path taken from the environment variable \envvar{PYTHONPATH}, or from |
| a built-in default if \envvar{PYTHONPATH} is not set. You can modify |
| it using standard list operations: |
| |
| \begin{verbatim} |
| >>> import sys |
| >>> sys.path.append('/ufs/guido/lib/python') |
| \end{verbatim} |
| |
| \section{The \function{dir()} Function \label{dir}} |
| |
| The built-in function \function{dir()} is used to find out which names |
| a module defines. It returns a sorted list of strings: |
| |
| \begin{verbatim} |
| >>> import fibo, sys |
| >>> dir(fibo) |
| ['__name__', 'fib', 'fib2'] |
| >>> dir(sys) |
| ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__', |
| '__stdin__', '__stdout__', '_getframe', 'argv', 'builtin_module_names', |
| 'byteorder', 'copyright', 'displayhook', 'exc_info', 'exc_type', |
| 'excepthook', 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', |
| 'getdlopenflags', 'getrecursionlimit', 'getrefcount', 'hexversion', |
| 'maxint', 'maxunicode', 'modules', 'path', 'platform', 'prefix', 'ps1', |
| 'ps2', 'setcheckinterval', 'setdlopenflags', 'setprofile', |
| 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', 'version', |
| 'version_info', 'warnoptions'] |
| \end{verbatim} |
| |
| Without arguments, \function{dir()} lists the names you have defined |
| currently: |
| |
| \begin{verbatim} |
| >>> a = [1, 2, 3, 4, 5] |
| >>> import fibo, sys |
| >>> fib = fibo.fib |
| >>> dir() |
| ['__name__', 'a', 'fib', 'fibo', 'sys'] |
| \end{verbatim} |
| |
| Note that it lists all types of names: variables, modules, functions, etc. |
| |
| \function{dir()} does not list the names of built-in functions and |
| variables. If you want a list of those, they are defined in the |
| standard module \module{__builtin__}\refbimodindex{__builtin__}: |
| |
| \begin{verbatim} |
| >>> import __builtin__ |
| >>> dir(__builtin__) |
| ['ArithmeticError', 'AssertionError', 'AttributeError', |
| 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', |
| 'Exception', 'FloatingPointError', 'IOError', 'ImportError', |
| 'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt', |
| 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented', |
| 'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning', |
| 'ReferenceError', 'RuntimeError', 'RuntimeWarning', 'StandardError', |
| 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', |
| 'SystemExit', 'TabError', 'TypeError', 'UnboundLocalError', |
| 'UnicodeError', 'UserWarning', 'ValueError', 'Warning', |
| 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__', |
| '__name__', 'abs', 'apply', 'buffer', 'callable', 'chr', 'classmethod', |
| 'cmp', 'coerce', 'compile', 'complex', 'copyright', 'credits', 'delattr', |
| 'dict', 'dir', 'divmod', 'eval', 'execfile', 'exit', 'file', 'filter', |
| 'float', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', |
| 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len', |
| 'license', 'list', 'locals', 'long', 'map', 'max', 'min', 'object', |
| 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range', 'raw_input', |
| 'reduce', 'reload', 'repr', 'round', 'setattr', 'slice', 'staticmethod', |
| 'str', 'super', 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', |
| 'zip'] |
| \end{verbatim} |
| |
| |
| \section{Packages \label{packages}} |
| |
| Packages are a way of structuring Python's module namespace |
| by using ``dotted module names''. For example, the module name |
| \module{A.B} designates a submodule named \samp{B} in a package named |
| \samp{A}. Just like the use of modules saves the authors of different |
| modules from having to worry about each other's global variable names, |
| the use of dotted module names saves the authors of multi-module |
| packages like NumPy or the Python Imaging Library from having to worry |
| about each other's module names. |
| |
| Suppose you want to design a collection of modules (a ``package'') for |
| the uniform handling of sound files and sound data. There are many |
| different sound file formats (usually recognized by their extension, |
| for example: \file{.wav}, \file{.aiff}, \file{.au}), so you may need |
| to create and maintain a growing collection of modules for the |
| conversion between the various file formats. There are also many |
| different operations you might want to perform on sound data (such as |
| mixing, adding echo, applying an equalizer function, creating an |
| artificial stereo effect), so in addition you will be writing a |
| never-ending stream of modules to perform these operations. Here's a |
| possible structure for your package (expressed in terms of a |
| hierarchical filesystem): |
| |
| \begin{verbatim} |
| Sound/ Top-level package |
| __init__.py Initialize the sound package |
| Formats/ Subpackage for file format conversions |
| __init__.py |
| wavread.py |
| wavwrite.py |
| aiffread.py |
| aiffwrite.py |
| auread.py |
| auwrite.py |
| ... |
| Effects/ Subpackage for sound effects |
| __init__.py |
| echo.py |
| surround.py |
| reverse.py |
| ... |
| Filters/ Subpackage for filters |
| __init__.py |
| equalizer.py |
| vocoder.py |
| karaoke.py |
| ... |
| \end{verbatim} |
| |
| The \file{__init__.py} files are required to make Python treat the |
| directories as containing packages; this is done to prevent |
| directories with a common name, such as \samp{string}, from |
| unintentionally hiding valid modules that occur later on the module |
| search path. In the simplest case, \file{__init__.py} can just be an |
| empty file, but it can also execute initialization code for the |
| package or set the \code{__all__} variable, described later. |
| |
| Users of the package can import individual modules from the |
| package, for example: |
| |
| \begin{verbatim} |
| import Sound.Effects.echo |
| \end{verbatim} |
| |
| This loads the submodule \module{Sound.Effects.echo}. It must be referenced |
| with its full name. |
| |
| \begin{verbatim} |
| Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4) |
| \end{verbatim} |
| |
| An alternative way of importing the submodule is: |
| |
| \begin{verbatim} |
| from Sound.Effects import echo |
| \end{verbatim} |
| |
| This also loads the submodule \module{echo}, and makes it available without |
| its package prefix, so it can be used as follows: |
| |
| \begin{verbatim} |
| echo.echofilter(input, output, delay=0.7, atten=4) |
| \end{verbatim} |
| |
| Yet another variation is to import the desired function or variable directly: |
| |
| \begin{verbatim} |
| from Sound.Effects.echo import echofilter |
| \end{verbatim} |
| |
| Again, this loads the submodule \module{echo}, but this makes its function |
| \function{echofilter()} directly available: |
| |
| \begin{verbatim} |
| echofilter(input, output, delay=0.7, atten=4) |
| \end{verbatim} |
| |
| Note that when using \code{from \var{package} import \var{item}}, the |
| item can be either a submodule (or subpackage) of the package, or some |
| other name defined in the package, like a function, class or |
| variable. The \code{import} statement first tests whether the item is |
| defined in the package; if not, it assumes it is a module and attempts |
| to load it. If it fails to find it, an |
| \exception{ImportError} exception is raised. |
| |
| Contrarily, when using syntax like \code{import |
| \var{item.subitem.subsubitem}}, each item except for the last must be |
| a package; the last item can be a module or a package but can't be a |
| class or function or variable defined in the previous item. |
| |
| \subsection{Importing * From a Package \label{pkg-import-star}} |
| %The \code{__all__} Attribute |
| |
| Now what happens when the user writes \code{from Sound.Effects import |
| *}? Ideally, one would hope that this somehow goes out to the |
| filesystem, finds which submodules are present in the package, and |
| imports them all. Unfortunately, this operation does not work very |
| well on Mac and Windows platforms, where the filesystem does not |
| always have accurate information about the case of a filename! On |
| these platforms, there is no guaranteed way to know whether a file |
| \file{ECHO.PY} should be imported as a module \module{echo}, |
| \module{Echo} or \module{ECHO}. (For example, Windows 95 has the |
| annoying practice of showing all file names with a capitalized first |
| letter.) The DOS 8+3 filename restriction adds another interesting |
| problem for long module names. |
| |
| The only solution is for the package author to provide an explicit |
| index of the package. The import statement uses the following |
| convention: if a package's \file{__init__.py} code defines a list |
| named \code{__all__}, it is taken to be the list of module names that |
| should be imported when \code{from \var{package} import *} is |
| encountered. It is up to the package author to keep this list |
| up-to-date when a new version of the package is released. Package |
| authors may also decide not to support it, if they don't see a use for |
| importing * from their package. For example, the file |
| \file{Sounds/Effects/__init__.py} could contain the following code: |
| |
| \begin{verbatim} |
| __all__ = ["echo", "surround", "reverse"] |
| \end{verbatim} |
| |
| This would mean that \code{from Sound.Effects import *} would |
| import the three named submodules of the \module{Sound} package. |
| |
| If \code{__all__} is not defined, the statement \code{from Sound.Effects |
| import *} does \emph{not} import all submodules from the package |
| \module{Sound.Effects} into the current namespace; it only ensures that the |
| package \module{Sound.Effects} has been imported (possibly running its |
| initialization code, \file{__init__.py}) and then imports whatever names are |
| defined in the package. This includes any names defined (and |
| submodules explicitly loaded) by \file{__init__.py}. It also includes any |
| submodules of the package that were explicitly loaded by previous |
| import statements. Consider this code: |
| |
| \begin{verbatim} |
| import Sound.Effects.echo |
| import Sound.Effects.surround |
| from Sound.Effects import * |
| \end{verbatim} |
| |
| In this example, the echo and surround modules are imported in the |
| current namespace because they are defined in the |
| \module{Sound.Effects} package when the \code{from...import} statement |
| is executed. (This also works when \code{__all__} is defined.) |
| |
| Note that in general the practicing of importing * from a module or |
| package is frowned upon, since it often causes poorly readable code. |
| However, it is okay to use it to save typing in interactive sessions, |
| and certain modules are designed to export only names that follow |
| certain patterns. |
| |
| Remember, there is nothing wrong with using \code{from Package |
| import specific_submodule}! In fact, this is the |
| recommended notation unless the importing module needs to use |
| submodules with the same name from different packages. |
| |
| |
| \subsection{Intra-package References} |
| |
| The submodules often need to refer to each other. For example, the |
| \module{surround} module might use the \module{echo} module. In fact, such references |
| are so common that the \code{import} statement first looks in the |
| containing package before looking in the standard module search path. |
| Thus, the surround module can simply use \code{import echo} or |
| \code{from echo import echofilter}. If the imported module is not |
| found in the current package (the package of which the current module |
| is a submodule), the \code{import} statement looks for a top-level module |
| with the given name. |
| |
| When packages are structured into subpackages (as with the |
| \module{Sound} package in the example), there's no shortcut to refer |
| to submodules of sibling packages - the full name of the subpackage |
| must be used. For example, if the module |
| \module{Sound.Filters.vocoder} needs to use the \module{echo} module |
| in the \module{Sound.Effects} package, it can use \code{from |
| Sound.Effects import echo}. |
| |
| %(One could design a notation to refer to parent packages, similar to |
| %the use of ".." to refer to the parent directory in \UNIX{} and Windows |
| %filesystems. In fact, the \module{ni} module, which was the |
| %ancestor of this package system, supported this using \code{__} for |
| %the package containing the current module, |
| %\code{__.__} for the parent package, and so on. This feature was dropped |
| %because of its awkwardness; since most packages will have a relative |
| %shallow substructure, this is no big loss.) |
| |
| |
| |
| \chapter{Input and Output \label{io}} |
| |
| There are several ways to present the output of a program; data can be |
| printed in a human-readable form, or written to a file for future use. |
| This chapter will discuss some of the possibilities. |
| |
| |
| \section{Fancier Output Formatting \label{formatting}} |
| |
| So far we've encountered two ways of writing values: \emph{expression |
| statements} and the \keyword{print} statement. (A third way is using |
| the \method{write()} method of file objects; the standard output file |
| can be referenced as \code{sys.stdout}. See the Library Reference for |
| more information on this.) |
| |
| Often you'll want more control over the formatting of your output than |
| simply printing space-separated values. There are two ways to format |
| your output; the first way is to do all the string handling yourself; |
| using string slicing and concatenation operations you can create any |
| lay-out you can imagine. The standard module |
| \module{string}\refstmodindex{string} contains some useful operations |
| for padding strings to a given column width; these will be discussed |
| shortly. The second way is to use the \code{\%} operator with a |
| string as the left argument. The \code{\%} operator interprets the |
| left argument much like a \cfunction{sprintf()}-style format |
| string to be applied to the right argument, and returns the string |
| resulting from this formatting operation. |
| |
| One question remains, of course: how do you convert values to strings? |
| Luckily, Python has ways to convert any value to a string: pass it to |
| the \function{repr()} or \function{str()} functions, or just write |
| the value between reverse quotes (\code{``}, equivalent to |
| \function{repr()}). |
| |
| The \function{str()} function is meant to return representations of |
| values which are fairly human-readable, while \function{repr()} is |
| meant to generate representations which can be read by the interpreter |
| (or will force a \exception{SyntaxError} if there is not equivalent |
| syntax). For objects which don't have a particular representation for |
| human consumption, \function{str()} will return the same value as |
| \function{repr()}. Many values, such as numbers or structures like |
| lists and dictionaries, have the same representation using either |
| function. Strings and floating point numbers, in particular, have two |
| distinct representations. |
| |
| Some examples: |
| |
| \begin{verbatim} |
| >>> s = 'Hello, world.' |
| >>> str(s) |
| 'Hello, world.' |
| >>> `s` |
| "'Hello, world.'" |
| >>> str(0.1) |
| '0.1' |
| >>> `0.1` |
| '0.10000000000000001' |
| >>> x = 10 * 3.25 |
| >>> y = 200 * 200 |
| >>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...' |
| >>> print s |
| The value of x is 32.5, and y is 40000... |
| >>> # Reverse quotes work on other types besides numbers: |
| ... p = [x, y] |
| >>> ps = repr(p) |
| >>> ps |
| '[32.5, 40000]' |
| >>> # Converting a string adds string quotes and backslashes: |
| ... hello = 'hello, world\n' |
| >>> hellos = `hello` |
| >>> print hellos |
| 'hello, world\n' |
| >>> # The argument of reverse quotes may be a tuple: |
| ... `x, y, ('spam', 'eggs')` |
| "(32.5, 40000, ('spam', 'eggs'))" |
| \end{verbatim} |
| |
| Here are two ways to write a table of squares and cubes: |
| |
| \begin{verbatim} |
| >>> import string |
| >>> for x in range(1, 11): |
| ... print string.rjust(`x`, 2), string.rjust(`x*x`, 3), |
| ... # Note trailing comma on previous line |
| ... print string.rjust(`x*x*x`, 4) |
| ... |
| 1 1 1 |
| 2 4 8 |
| 3 9 27 |
| 4 16 64 |
| 5 25 125 |
| 6 36 216 |
| 7 49 343 |
| 8 64 512 |
| 9 81 729 |
| 10 100 1000 |
| >>> for x in range(1,11): |
| ... print '%2d %3d %4d' % (x, x*x, x*x*x) |
| ... |
| 1 1 1 |
| 2 4 8 |
| 3 9 27 |
| 4 16 64 |
| 5 25 125 |
| 6 36 216 |
| 7 49 343 |
| 8 64 512 |
| 9 81 729 |
| 10 100 1000 |
| \end{verbatim} |
| |
| (Note that one space between each column was added by the way |
| \keyword{print} works: it always adds spaces between its arguments.) |
| |
| This example demonstrates the function \function{string.rjust()}, |
| which right-justifies a string in a field of a given width by padding |
| it with spaces on the left. There are similar functions |
| \function{string.ljust()} and \function{string.center()}. These |
| functions do not write anything, they just return a new string. If |
| the input string is too long, they don't truncate it, but return it |
| unchanged; this will mess up your column lay-out but that's usually |
| better than the alternative, which would be lying about a value. (If |
| you really want truncation you can always add a slice operation, as in |
| \samp{string.ljust(x,~n)[0:n]}.) |
| |
| There is another function, \function{string.zfill()}, which pads a |
| numeric string on the left with zeros. It understands about plus and |
| minus signs: |
| |
| \begin{verbatim} |
| >>> import string |
| >>> string.zfill('12', 5) |
| '00012' |
| >>> string.zfill('-3.14', 7) |
| '-003.14' |
| >>> string.zfill('3.14159265359', 5) |
| '3.14159265359' |
| \end{verbatim} |
| |
| Using the \code{\%} operator looks like this: |
| |
| \begin{verbatim} |
| >>> import math |
| >>> print 'The value of PI is approximately %5.3f.' % math.pi |
| The value of PI is approximately 3.142. |
| \end{verbatim} |
| |
| If there is more than one format in the string, you need to pass a |
| tuple as right operand, as in this example: |
| |
| \begin{verbatim} |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678} |
| >>> for name, phone in table.items(): |
| ... print '%-10s ==> %10d' % (name, phone) |
| ... |
| Jack ==> 4098 |
| Dcab ==> 7678 |
| Sjoerd ==> 4127 |
| \end{verbatim} |
| |
| Most formats work exactly as in C and require that you pass the proper |
| type; however, if you don't you get an exception, not a core dump. |
| The \code{\%s} format is more relaxed: if the corresponding argument is |
| not a string object, it is converted to string using the |
| \function{str()} built-in function. Using \code{*} to pass the width |
| or precision in as a separate (integer) argument is supported. The |
| C formats \code{\%n} and \code{\%p} are not supported. |
| |
| If you have a really long format string that you don't want to split |
| up, it would be nice if you could reference the variables to be |
| formatted by name instead of by position. This can be done by using |
| form \code{\%(name)format}, as shown here: |
| |
| \begin{verbatim} |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table |
| Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
| \end{verbatim} |
| |
| This is particularly useful in combination with the new built-in |
| \function{vars()} function, which returns a dictionary containing all |
| local variables. |
| |
| \section{Reading and Writing Files \label{files}} |
| |
| % Opening files |
| \function{open()}\bifuncindex{open} returns a file |
| object\obindex{file}, and is most commonly used with two arguments: |
| \samp{open(\var{filename}, \var{mode})}. |
| |
| \begin{verbatim} |
| >>> f=open('/tmp/workfile', 'w') |
| >>> print f |
| <open file '/tmp/workfile', mode 'w' at 80a0960> |
| \end{verbatim} |
| |
| The first argument is a string containing the filename. The second |
| argument is another string containing a few characters describing the |
| way in which the file will be used. \var{mode} can be \code{'r'} when |
| the file will only be read, \code{'w'} for only writing (an existing |
| file with the same name will be erased), and \code{'a'} opens the file |
| for appending; any data written to the file is automatically added to |
| the end. \code{'r+'} opens the file for both reading and writing. |
| The \var{mode} argument is optional; \code{'r'} will be assumed if |
| it's omitted. |
| |
| On Windows and the Macintosh, \code{'b'} appended to the |
| mode opens the file in binary mode, so there are also modes like |
| \code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a |
| distinction between text and binary files; the end-of-line characters |
| in text files are automatically altered slightly when data is read or |
| written. This behind-the-scenes modification to file data is fine for |
| \ASCII{} text files, but it'll corrupt binary data like that in JPEGs or |
| \file{.EXE} files. Be very careful to use binary mode when reading and |
| writing such files. (Note that the precise semantics of text mode on |
| the Macintosh depends on the underlying C library being used.) |
| |
| \subsection{Methods of File Objects \label{fileMethods}} |
| |
| The rest of the examples in this section will assume that a file |
| object called \code{f} has already been created. |
| |
| To read a file's contents, call \code{f.read(\var{size})}, which reads |
| some quantity of data and returns it as a string. \var{size} is an |
| optional numeric argument. When \var{size} is omitted or negative, |
| the entire contents of the file will be read and returned; it's your |
| problem if the file is twice as large as your machine's memory. |
| Otherwise, at most \var{size} bytes are read and returned. If the end |
| of the file has been reached, \code{f.read()} will return an empty |
| string (\code {""}). |
| \begin{verbatim} |
| >>> f.read() |
| 'This is the entire file.\n' |
| >>> f.read() |
| '' |
| \end{verbatim} |
| |
| \code{f.readline()} reads a single line from the file; a newline |
| character (\code{\e n}) is left at the end of the string, and is only |
| omitted on the last line of the file if the file doesn't end in a |
| newline. This makes the return value unambiguous; if |
| \code{f.readline()} returns an empty string, the end of the file has |
| been reached, while a blank line is represented by \code{'\e n'}, a |
| string containing only a single newline. |
| |
| \begin{verbatim} |
| >>> f.readline() |
| 'This is the first line of the file.\n' |
| >>> f.readline() |
| 'Second line of the file\n' |
| >>> f.readline() |
| '' |
| \end{verbatim} |
| |
| \code{f.readlines()} returns a list containing all the lines of data |
| in the file. If given an optional parameter \var{sizehint}, it reads |
| that many bytes from the file and enough more to complete a line, and |
| returns the lines from that. This is often used to allow efficient |
| reading of a large file by lines, but without having to load the |
| entire file in memory. Only complete lines will be returned. |
| |
| \begin{verbatim} |
| >>> f.readlines() |
| ['This is the first line of the file.\n', 'Second line of the file\n'] |
| \end{verbatim} |
| |
| \code{f.write(\var{string})} writes the contents of \var{string} to |
| the file, returning \code{None}. |
| |
| \begin{verbatim} |
| >>> f.write('This is a test\n') |
| \end{verbatim} |
| |
| \code{f.tell()} returns an integer giving the file object's current |
| position in the file, measured in bytes from the beginning of the |
| file. To change the file object's position, use |
| \samp{f.seek(\var{offset}, \var{from_what})}. The position is |
| computed from adding \var{offset} to a reference point; the reference |
| point is selected by the \var{from_what} argument. A |
| \var{from_what} value of 0 measures from the beginning of the file, 1 |
| uses the current file position, and 2 uses the end of the file as the |
| reference point. \var{from_what} can be omitted and defaults to 0, |
| using the beginning of the file as the reference point. |
| |
| \begin{verbatim} |
| >>> f=open('/tmp/workfile', 'r+') |
| >>> f.write('0123456789abcdef') |
| >>> f.seek(5) # Go to the 6th byte in the file |
| >>> f.read(1) |
| '5' |
| >>> f.seek(-3, 2) # Go to the 3rd byte before the end |
| >>> f.read(1) |
| 'd' |
| \end{verbatim} |
| |
| When you're done with a file, call \code{f.close()} to close it and |
| free up any system resources taken up by the open file. After calling |
| \code{f.close()}, attempts to use the file object will automatically fail. |
| |
| \begin{verbatim} |
| >>> f.close() |
| >>> f.read() |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: I/O operation on closed file |
| \end{verbatim} |
| |
| File objects have some additional methods, such as |
| \method{isatty()} and \method{truncate()} which are less frequently |
| used; consult the Library Reference for a complete guide to file |
| objects. |
| |
| \subsection{The \module{pickle} Module \label{pickle}} |
| \refstmodindex{pickle} |
| |
| Strings can easily be written to and read from a file. Numbers take a |
| bit more effort, since the \method{read()} method only returns |
| strings, which will have to be passed to a function like |
| \function{string.atoi()}, which takes a string like \code{'123'} and |
| returns its numeric value 123. However, when you want to save more |
| complex data types like lists, dictionaries, or class instances, |
| things get a lot more complicated. |
| |
| Rather than have users be constantly writing and debugging code to |
| save complicated data types, Python provides a standard module called |
| \module{pickle}. This is an amazing module that can take almost |
| any Python object (even some forms of Python code!), and convert it to |
| a string representation; this process is called \dfn{pickling}. |
| Reconstructing the object from the string representation is called |
| \dfn{unpickling}. Between pickling and unpickling, the string |
| representing the object may have been stored in a file or data, or |
| sent over a network connection to some distant machine. |
| |
| If you have an object \code{x}, and a file object \code{f} that's been |
| opened for writing, the simplest way to pickle the object takes only |
| one line of code: |
| |
| \begin{verbatim} |
| pickle.dump(x, f) |
| \end{verbatim} |
| |
| To unpickle the object again, if \code{f} is a file object which has |
| been opened for reading: |
| |
| \begin{verbatim} |
| x = pickle.load(f) |
| \end{verbatim} |
| |
| (There are other variants of this, used when pickling many objects or |
| when you don't want to write the pickled data to a file; consult the |
| complete documentation for \module{pickle} in the Library Reference.) |
| |
| \module{pickle} is the standard way to make Python objects which can |
| be stored and reused by other programs or by a future invocation of |
| the same program; the technical term for this is a |
| \dfn{persistent} object. Because \module{pickle} is so widely used, |
| many authors who write Python extensions take care to ensure that new |
| data types such as matrices can be properly pickled and unpickled. |
| |
| |
| |
| \chapter{Errors and Exceptions \label{errors}} |
| |
| Until now error messages haven't been more than mentioned, but if you |
| have tried out the examples you have probably seen some. There are |
| (at least) two distinguishable kinds of errors: |
| \emph{syntax errors} and \emph{exceptions}. |
| |
| \section{Syntax Errors \label{syntaxErrors}} |
| |
| Syntax errors, also known as parsing errors, are perhaps the most common |
| kind of complaint you get while you are still learning Python: |
| |
| \begin{verbatim} |
| >>> while 1 print 'Hello world' |
| File "<stdin>", line 1, in ? |
| while 1 print 'Hello world' |
| ^ |
| SyntaxError: invalid syntax |
| \end{verbatim} |
| |
| The parser repeats the offending line and displays a little `arrow' |
| pointing at the earliest point in the line where the error was |
| detected. The error is caused by (or at least detected at) the token |
| \emph{preceding} the arrow: in the example, the error is detected at |
| the keyword \keyword{print}, since a colon (\character{:}) is missing |
| before it. File name and line number are printed so you know where to |
| look in case the input came from a script. |
| |
| \section{Exceptions \label{exceptions}} |
| |
| Even if a statement or expression is syntactically correct, it may |
| cause an error when an attempt is made to execute it. |
| Errors detected during execution are called \emph{exceptions} and are |
| not unconditionally fatal: you will soon learn how to handle them in |
| Python programs. Most exceptions are not handled by programs, |
| however, and result in error messages as shown here: |
| |
| \begin{verbatim} |
| >>> 10 * (1/0) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ZeroDivisionError: integer division or modulo |
| >>> 4 + spam*3 |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| NameError: spam |
| >>> '2' + 2 |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: illegal argument type for built-in operation |
| \end{verbatim} |
| |
| The last line of the error message indicates what happened. |
| Exceptions come in different types, and the type is printed as part of |
| the message: the types in the example are |
| \exception{ZeroDivisionError}, \exception{NameError} and |
| \exception{TypeError}. |
| The string printed as the exception type is the name of the built-in |
| name for the exception that occurred. This is true for all built-in |
| exceptions, but need not be true for user-defined exceptions (although |
| it is a useful convention). |
| Standard exception names are built-in identifiers (not reserved |
| keywords). |
| |
| The rest of the line is a detail whose interpretation depends on the |
| exception type; its meaning is dependent on the exception type. |
| |
| The preceding part of the error message shows the context where the |
| exception happened, in the form of a stack backtrace. |
| In general it contains a stack backtrace listing source lines; however, |
| it will not display lines read from standard input. |
| |
| The \citetitle[../lib/module-exceptions.html]{Python Library |
| Reference} lists the built-in exceptions and their meanings. |
| |
| |
| \section{Handling Exceptions \label{handling}} |
| |
| It is possible to write programs that handle selected exceptions. |
| Look at the following example, which asks the user for input until a |
| valid integer has been entered, but allows the user to interrupt the |
| program (using \kbd{Control-C} or whatever the operating system |
| supports); note that a user-generated interruption is signalled by |
| raising the \exception{KeyboardInterrupt} exception. |
| |
| \begin{verbatim} |
| >>> while 1: |
| ... try: |
| ... x = int(raw_input("Please enter a number: ")) |
| ... break |
| ... except ValueError: |
| ... print "Oops! That was no valid number. Try again..." |
| ... |
| \end{verbatim} |
| |
| The \keyword{try} statement works as follows. |
| |
| \begin{itemize} |
| \item |
| First, the \emph{try clause} (the statement(s) between the |
| \keyword{try} and \keyword{except} keywords) is executed. |
| |
| \item |
| If no exception occurs, the \emph{except\ clause} is skipped and |
| execution of the \keyword{try} statement is finished. |
| |
| \item |
| If an exception occurs during execution of the try clause, the rest of |
| the clause is skipped. Then if its type matches the exception named |
| after the \keyword{except} keyword, the rest of the try clause is |
| skipped, the except clause is executed, and then execution continues |
| after the \keyword{try} statement. |
| |
| \item |
| If an exception occurs which does not match the exception named in the |
| except clause, it is passed on to outer \keyword{try} statements; if |
| no handler is found, it is an \emph{unhandled exception} and execution |
| stops with a message as shown above. |
| |
| \end{itemize} |
| |
| A \keyword{try} statement may have more than one except clause, to |
| specify handlers for different exceptions. At most one handler will |
| be executed. Handlers only handle exceptions that occur in the |
| corresponding try clause, not in other handlers of the same |
| \keyword{try} statement. An except clause may name multiple exceptions |
| as a parenthesized list, for example: |
| |
| \begin{verbatim} |
| ... except (RuntimeError, TypeError, NameError): |
| ... pass |
| \end{verbatim} |
| |
| The last except clause may omit the exception name(s), to serve as a |
| wildcard. Use this with extreme caution, since it is easy to mask a |
| real programming error in this way! It can also be used to print an |
| error message and then re-raise the exception (allowing a caller to |
| handle the exception as well): |
| |
| \begin{verbatim} |
| import string, sys |
| |
| try: |
| f = open('myfile.txt') |
| s = f.readline() |
| i = int(string.strip(s)) |
| except IOError, (errno, strerror): |
| print "I/O error(%s): %s" % (errno, strerror) |
| except ValueError: |
| print "Could not convert data to an integer." |
| except: |
| print "Unexpected error:", sys.exc_info()[0] |
| raise |
| \end{verbatim} |
| |
| The \keyword{try} \ldots\ \keyword{except} statement has an optional |
| \emph{else clause}, which, when present, must follow all except |
| clauses. It is useful for code that must be executed if the try |
| clause does not raise an exception. For example: |
| |
| \begin{verbatim} |
| for arg in sys.argv[1:]: |
| try: |
| f = open(arg, 'r') |
| except IOError: |
| print 'cannot open', arg |
| else: |
| print arg, 'has', len(f.readlines()), 'lines' |
| f.close() |
| \end{verbatim} |
| |
| The use of the \keyword{else} clause is better than adding additional |
| code to the \keyword{try} clause because it avoids accidentally |
| catching an exception that wasn't raised by the code being protected |
| by the \keyword{try} \ldots\ \keyword{except} statement. |
| |
| |
| When an exception occurs, it may have an associated value, also known as |
| the exception's \emph{argument}. |
| The presence and type of the argument depend on the exception type. |
| For exception types which have an argument, the except clause may |
| specify a variable after the exception name (or list) to receive the |
| argument's value, as follows: |
| |
| \begin{verbatim} |
| >>> try: |
| ... spam() |
| ... except NameError, x: |
| ... print 'name', x, 'undefined' |
| ... |
| name spam undefined |
| \end{verbatim} |
| |
| If an exception has an argument, it is printed as the last part |
| (`detail') of the message for unhandled exceptions. |
| |
| Exception handlers don't just handle exceptions if they occur |
| immediately in the try clause, but also if they occur inside functions |
| that are called (even indirectly) in the try clause. |
| For example: |
| |
| \begin{verbatim} |
| >>> def this_fails(): |
| ... x = 1/0 |
| ... |
| >>> try: |
| ... this_fails() |
| ... except ZeroDivisionError, detail: |
| ... print 'Handling run-time error:', detail |
| ... |
| Handling run-time error: integer division or modulo |
| \end{verbatim} |
| |
| |
| \section{Raising Exceptions \label{raising}} |
| |
| The \keyword{raise} statement allows the programmer to force a |
| specified exception to occur. |
| For example: |
| |
| \begin{verbatim} |
| >>> raise NameError, 'HiThere' |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| NameError: HiThere |
| \end{verbatim} |
| |
| The first argument to \keyword{raise} names the exception to be |
| raised. The optional second argument specifies the exception's |
| argument. |
| |
| If you need to determine whether an exception was raised but don't |
| intend to handle it, a simpler form of the \keyword{raise} statement |
| allows you to re-raise the exception: |
| |
| \begin{verbatim} |
| >>> try: |
| ... raise NameError, 'HiThere' |
| ... except NameError: |
| ... print 'An exception flew by!' |
| ... raise |
| ... |
| An exception flew by! |
| Traceback (most recent call last): |
| File "<stdin>", line 2, in ? |
| NameError: HiThere |
| \end{verbatim} |
| |
| |
| \section{User-defined Exceptions \label{userExceptions}} |
| |
| Programs may name their own exceptions by creating a new exception |
| class. Exceptions should typically be derived from the |
| \exception{Exception} class, either directly or indirectly. For |
| example: |
| |
| \begin{verbatim} |
| >>> class MyError(Exception): |
| ... def __init__(self, value): |
| ... self.value = value |
| ... def __str__(self): |
| ... return `self.value` |
| ... |
| >>> try: |
| ... raise MyError(2*2) |
| ... except MyError, e: |
| ... print 'My exception occurred, value:', e.value |
| ... |
| My exception occurred, value: 4 |
| >>> raise MyError, 'oops!' |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| __main__.MyError: 'oops!' |
| \end{verbatim} |
| |
| Exception classes can be defined which do anything any other class can |
| do, but are usually kept simple, often only offering a number of |
| attributes that allow information about the error to be extracted by |
| handlers for the exception. When creating a module which can raise |
| several distinct errors, a common practice is to create a base class |
| for exceptions defined by that module, and subclass that to create |
| specific exception classes for different error conditions: |
| |
| \begin{verbatim} |
| class Error(Exception): |
| """Base class for exceptions in this module.""" |
| pass |
| |
| class InputError(Error): |
| """Exception raised for errors in the input. |
| |
| Attributes: |
| expression -- input expression in which the error occurred |
| message -- explanation of the error |
| """ |
| |
| def __init__(self, expression, message): |
| self.expression = expression |
| self.message = message |
| |
| class TransitionError(Error): |
| """Raised when an operation attempts a state transition that's not |
| allowed. |
| |
| Attributes: |
| previous -- state at beginning of transition |
| next -- attempted new state |
| message -- explanation of why the specific transition is not allowed |
| """ |
| |
| def __init__(self, previous, next, message): |
| self.previous = previous |
| self.next = next |
| self.message = message |
| \end{verbatim} |
| |
| Most exceptions are defined with names that end in ``Error,'' similar |
| to the naming of the standard exceptions. |
| |
| Many standard modules define their own exceptions to report errors |
| that may occur in functions they define. More information on classes |
| is presented in chapter \ref{classes}, ``Classes.'' |
| |
| |
| \section{Defining Clean-up Actions \label{cleanup}} |
| |
| The \keyword{try} statement has another optional clause which is |
| intended to define clean-up actions that must be executed under all |
| circumstances. For example: |
| |
| \begin{verbatim} |
| >>> try: |
| ... raise KeyboardInterrupt |
| ... finally: |
| ... print 'Goodbye, world!' |
| ... |
| Goodbye, world! |
| Traceback (most recent call last): |
| File "<stdin>", line 2, in ? |
| KeyboardInterrupt |
| \end{verbatim} |
| |
| A \emph{finally clause} is executed whether or not an exception has |
| occurred in the try clause. When an exception has occurred, it is |
| re-raised after the finally clause is executed. The finally clause is |
| also executed ``on the way out'' when the \keyword{try} statement is |
| left via a \keyword{break} or \keyword{return} statement. |
| |
| The code in the finally clause is useful for releasing external |
| resources (such as files or network connections), regardless of |
| whether or not the use of the resource was successful. |
| |
| A \keyword{try} statement must either have one or more except clauses |
| or one finally clause, but not both. |
| |
| |
| \chapter{Classes \label{classes}} |
| |
| Python's class mechanism adds classes to the language with a minimum |
| of new syntax and semantics. It is a mixture of the class mechanisms |
| found in \Cpp{} and Modula-3. As is true for modules, classes in Python |
| do not put an absolute barrier between definition and user, but rather |
| rely on the politeness of the user not to ``break into the |
| definition.'' The most important features of classes are retained |
| with full power, however: the class inheritance mechanism allows |
| multiple base classes, a derived class can override any methods of its |
| base class or classes, a method can call the method of a base class with the |
| same name. Objects can contain an arbitrary amount of private data. |
| |
| In \Cpp{} terminology, all class members (including the data members) are |
| \emph{public}, and all member functions are \emph{virtual}. There are |
| no special constructors or destructors. As in Modula-3, there are no |
| shorthands for referencing the object's members from its methods: the |
| method function is declared with an explicit first argument |
| representing the object, which is provided implicitly by the call. As |
| in Smalltalk, classes themselves are objects, albeit in the wider |
| sense of the word: in Python, all data types are objects. This |
| provides semantics for importing and renaming. But, just like in |
| \Cpp{} or Modula-3, built-in types cannot be used as base classes for |
| extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most |
| built-in operators with special syntax (arithmetic operators, |
| subscripting etc.) can be redefined for class instances. |
| |
| \section{A Word About Terminology \label{terminology}} |
| |
| Lacking universally accepted terminology to talk about classes, I will |
| make occasional use of Smalltalk and \Cpp{} terms. (I would use Modula-3 |
| terms, since its object-oriented semantics are closer to those of |
| Python than \Cpp, but I expect that few readers have heard of it.) |
| |
| I also have to warn you that there's a terminological pitfall for |
| object-oriented readers: the word ``object'' in Python does not |
| necessarily mean a class instance. Like \Cpp{} and Modula-3, and |
| unlike Smalltalk, not all types in Python are classes: the basic |
| built-in types like integers and lists are not, and even somewhat more |
| exotic types like files aren't. However, \emph{all} Python types |
| share a little bit of common semantics that is best described by using |
| the word object. |
| |
| Objects have individuality, and multiple names (in multiple scopes) |
| can be bound to the same object. This is known as aliasing in other |
| languages. This is usually not appreciated on a first glance at |
| Python, and can be safely ignored when dealing with immutable basic |
| types (numbers, strings, tuples). However, aliasing has an |
| (intended!) effect on the semantics of Python code involving mutable |
| objects such as lists, dictionaries, and most types representing |
| entities outside the program (files, windows, etc.). This is usually |
| used to the benefit of the program, since aliases behave like pointers |
| in some respects. For example, passing an object is cheap since only |
| a pointer is passed by the implementation; and if a function modifies |
| an object passed as an argument, the caller will see the change --- this |
| obviates the need for two different argument passing mechanisms as in |
| Pascal. |
| |
| |
| \section{Python Scopes and Name Spaces \label{scopes}} |
| |
| Before introducing classes, I first have to tell you something about |
| Python's scope rules. Class definitions play some neat tricks with |
| namespaces, and you need to know how scopes and namespaces work to |
| fully understand what's going on. Incidentally, knowledge about this |
| subject is useful for any advanced Python programmer. |
| |
| Let's begin with some definitions. |
| |
| A \emph{namespace} is a mapping from names to objects. Most |
| namespaces are currently implemented as Python dictionaries, but |
| that's normally not noticeable in any way (except for performance), |
| and it may change in the future. Examples of namespaces are: the set |
| of built-in names (functions such as \function{abs()}, and built-in |
| exception names); the global names in a module; and the local names in |
| a function invocation. In a sense the set of attributes of an object |
| also form a namespace. The important thing to know about namespaces |
| is that there is absolutely no relation between names in different |
| namespaces; for instance, two different modules may both define a |
| function ``maximize'' without confusion --- users of the modules must |
| prefix it with the module name. |
| |
| By the way, I use the word \emph{attribute} for any name following a |
| dot --- for example, in the expression \code{z.real}, \code{real} is |
| an attribute of the object \code{z}. Strictly speaking, references to |
| names in modules are attribute references: in the expression |
| \code{modname.funcname}, \code{modname} is a module object and |
| \code{funcname} is an attribute of it. In this case there happens to |
| be a straightforward mapping between the module's attributes and the |
| global names defined in the module: they share the same namespace! |
| \footnote{ |
| Except for one thing. Module objects have a secret read-only |
| attribute called \member{__dict__} which returns the dictionary |
| used to implement the module's namespace; the name |
| \member{__dict__} is an attribute but not a global name. |
| Obviously, using this violates the abstraction of namespace |
| implementation, and should be restricted to things like |
| post-mortem debuggers. |
| } |
| |
| Attributes may be read-only or writable. In the latter case, |
| assignment to attributes is possible. Module attributes are writable: |
| you can write \samp{modname.the_answer = 42}. Writable attributes may |
| also be deleted with the \keyword{del} statement. For example, |
| \samp{del modname.the_answer} will remove the attribute |
| \member{the_answer} from the object named by \code{modname}. |
| |
| Name spaces are created at different moments and have different |
| lifetimes. The namespace containing the built-in names is created |
| when the Python interpreter starts up, and is never deleted. The |
| global namespace for a module is created when the module definition |
| is read in; normally, module namespaces also last until the |
| interpreter quits. The statements executed by the top-level |
| invocation of the interpreter, either read from a script file or |
| interactively, are considered part of a module called |
| \module{__main__}, so they have their own global namespace. (The |
| built-in names actually also live in a module; this is called |
| \module{__builtin__}.) |
| |
| The local namespace for a function is created when the function is |
| called, and deleted when the function returns or raises an exception |
| that is not handled within the function. (Actually, forgetting would |
| be a better way to describe what actually happens.) Of course, |
| recursive invocations each have their own local namespace. |
| |
| A \emph{scope} is a textual region of a Python program where a |
| namespace is directly accessible. ``Directly accessible'' here means |
| that an unqualified reference to a name attempts to find the name in |
| the namespace. |
| |
| Although scopes are determined statically, they are used dynamically. |
| At any time during execution, exactly three nested scopes are in use |
| (exactly three namespaces are directly accessible): the |
| innermost scope, which is searched first, contains the local names, |
| the middle scope, searched next, contains the current module's global |
| names, and the outermost scope (searched last) is the namespace |
| containing built-in names. |
| |
| Usually, the local scope references the local names of the (textually) |
| current function. Outside of functions, the local scope references |
| the same namespace as the global scope: the module's namespace. |
| Class definitions place yet another namespace in the local scope. |
| |
| It is important to realize that scopes are determined textually: the |
| global scope of a function defined in a module is that module's |
| namespace, no matter from where or by what alias the function is |
| called. On the other hand, the actual search for names is done |
| dynamically, at run time --- however, the language definition is |
| evolving towards static name resolution, at ``compile'' time, so don't |
| rely on dynamic name resolution! (In fact, local variables are |
| already determined statically.) |
| |
| A special quirk of Python is that assignments always go into the |
| innermost scope. Assignments do not copy data --- they just |
| bind names to objects. The same is true for deletions: the statement |
| \samp{del x} removes the binding of \code{x} from the namespace |
| referenced by the local scope. In fact, all operations that introduce |
| new names use the local scope: in particular, import statements and |
| function definitions bind the module or function name in the local |
| scope. (The \keyword{global} statement can be used to indicate that |
| particular variables live in the global scope.) |
| |
| |
| \section{A First Look at Classes \label{firstClasses}} |
| |
| Classes introduce a little bit of new syntax, three new object types, |
| and some new semantics. |
| |
| |
| \subsection{Class Definition Syntax \label{classDefinition}} |
| |
| The simplest form of class definition looks like this: |
| |
| \begin{verbatim} |
| class ClassName: |
| <statement-1> |
| . |
| . |
| . |
| <statement-N> |
| \end{verbatim} |
| |
| Class definitions, like function definitions |
| (\keyword{def} statements) must be executed before they have any |
| effect. (You could conceivably place a class definition in a branch |
| of an \keyword{if} statement, or inside a function.) |
| |
| In practice, the statements inside a class definition will usually be |
| function definitions, but other statements are allowed, and sometimes |
| useful --- we'll come back to this later. The function definitions |
| inside a class normally have a peculiar form of argument list, |
| dictated by the calling conventions for methods --- again, this is |
| explained later. |
| |
| When a class definition is entered, a new namespace is created, and |
| used as the local scope --- thus, all assignments to local variables |
| go into this new namespace. In particular, function definitions bind |
| the name of the new function here. |
| |
| When a class definition is left normally (via the end), a \emph{class |
| object} is created. This is basically a wrapper around the contents |
| of the namespace created by the class definition; we'll learn more |
| about class objects in the next section. The original local scope |
| (the one in effect just before the class definitions was entered) is |
| reinstated, and the class object is bound here to the class name given |
| in the class definition header (\class{ClassName} in the example). |
| |
| |
| \subsection{Class Objects \label{classObjects}} |
| |
| Class objects support two kinds of operations: attribute references |
| and instantiation. |
| |
| \emph{Attribute references} use the standard syntax used for all |
| attribute references in Python: \code{obj.name}. Valid attribute |
| names are all the names that were in the class's namespace when the |
| class object was created. So, if the class definition looked like |
| this: |
| |
| \begin{verbatim} |
| class MyClass: |
| "A simple example class" |
| i = 12345 |
| def f(self): |
| return 'hello world' |
| \end{verbatim} |
| |
| then \code{MyClass.i} and \code{MyClass.f} are valid attribute |
| references, returning an integer and a method object, respectively. |
| Class attributes can also be assigned to, so you can change the value |
| of \code{MyClass.i} by assignment. \member{__doc__} is also a valid |
| attribute, returning the docstring belonging to the class: \code{"A |
| simple example class"}). |
| |
| Class \emph{instantiation} uses function notation. Just pretend that |
| the class object is a parameterless function that returns a new |
| instance of the class. For example (assuming the above class): |
| |
| \begin{verbatim} |
| x = MyClass() |
| \end{verbatim} |
| |
| creates a new \emph{instance} of the class and assigns this object to |
| the local variable \code{x}. |
| |
| The instantiation operation (``calling'' a class object) creates an |
| empty object. Many classes like to create objects in a known initial |
| state. Therefore a class may define a special method named |
| \method{__init__()}, like this: |
| |
| \begin{verbatim} |
| def __init__(self): |
| self.data = [] |
| \end{verbatim} |
| |
| When a class defines an \method{__init__()} method, class |
| instantiation automatically invokes \method{__init__()} for the |
| newly-created class instance. So in this example, a new, initialized |
| instance can be obtained by: |
| |
| \begin{verbatim} |
| x = MyClass() |
| \end{verbatim} |
| |
| Of course, the \method{__init__()} method may have arguments for |
| greater flexibility. In that case, arguments given to the class |
| instantiation operator are passed on to \method{__init__()}. For |
| example, |
| |
| \begin{verbatim} |
| >>> class Complex: |
| ... def __init__(self, realpart, imagpart): |
| ... self.r = realpart |
| ... self.i = imagpart |
| ... |
| >>> x = Complex(3.0, -4.5) |
| >>> x.r, x.i |
| (3.0, -4.5) |
| \end{verbatim} |
| |
| |
| \subsection{Instance Objects \label{instanceObjects}} |
| |
| Now what can we do with instance objects? The only operations |
| understood by instance objects are attribute references. There are |
| two kinds of valid attribute names. |
| |
| The first I'll call \emph{data attributes}. These correspond to |
| ``instance variables'' in Smalltalk, and to ``data members'' in |
| \Cpp. Data attributes need not be declared; like local variables, |
| they spring into existence when they are first assigned to. For |
| example, if \code{x} is the instance of \class{MyClass} created above, |
| the following piece of code will print the value \code{16}, without |
| leaving a trace: |
| |
| \begin{verbatim} |
| x.counter = 1 |
| while x.counter < 10: |
| x.counter = x.counter * 2 |
| print x.counter |
| del x.counter |
| \end{verbatim} |
| |
| The second kind of attribute references understood by instance objects |
| are \emph{methods}. A method is a function that ``belongs to'' an |
| object. (In Python, the term method is not unique to class instances: |
| other object types can have methods as well. For example, list objects have |
| methods called append, insert, remove, sort, and so on. However, |
| below, we'll use the term method exclusively to mean methods of class |
| instance objects, unless explicitly stated otherwise.) |
| |
| Valid method names of an instance object depend on its class. By |
| definition, all attributes of a class that are (user-defined) function |
| objects define corresponding methods of its instances. So in our |
| example, \code{x.f} is a valid method reference, since |
| \code{MyClass.f} is a function, but \code{x.i} is not, since |
| \code{MyClass.i} is not. But \code{x.f} is not the same thing as |
| \code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not |
| a function object. |
| |
| |
| \subsection{Method Objects \label{methodObjects}} |
| |
| Usually, a method is called immediately: |
| |
| \begin{verbatim} |
| x.f() |
| \end{verbatim} |
| |
| In our example, this will return the string \code{'hello world'}. |
| However, it is not necessary to call a method right away: |
| \code{x.f} is a method object, and can be stored away and called at a |
| later time. For example: |
| |
| \begin{verbatim} |
| xf = x.f |
| while 1: |
| print xf() |
| \end{verbatim} |
| |
| will continue to print \samp{hello world} until the end of time. |
| |
| What exactly happens when a method is called? You may have noticed |
| that \code{x.f()} was called without an argument above, even though |
| the function definition for \method{f} specified an argument. What |
| happened to the argument? Surely Python raises an exception when a |
| function that requires an argument is called without any --- even if |
| the argument isn't actually used... |
| |
| Actually, you may have guessed the answer: the special thing about |
| methods is that the object is passed as the first argument of the |
| function. In our example, the call \code{x.f()} is exactly equivalent |
| to \code{MyClass.f(x)}. In general, calling a method with a list of |
| \var{n} arguments is equivalent to calling the corresponding function |
| with an argument list that is created by inserting the method's object |
| before the first argument. |
| |
| If you still don't understand how methods work, a look at the |
| implementation can perhaps clarify matters. When an instance |
| attribute is referenced that isn't a data attribute, its class is |
| searched. If the name denotes a valid class attribute that is a |
| function object, a method object is created by packing (pointers to) |
| the instance object and the function object just found together in an |
| abstract object: this is the method object. When the method object is |
| called with an argument list, it is unpacked again, a new argument |
| list is constructed from the instance object and the original argument |
| list, and the function object is called with this new argument list. |
| |
| |
| \section{Random Remarks \label{remarks}} |
| |
| [These should perhaps be placed more carefully...] |
| |
| |
| Data attributes override method attributes with the same name; to |
| avoid accidental name conflicts, which may cause hard-to-find bugs in |
| large programs, it is wise to use some kind of convention that |
| minimizes the chance of conflicts. Possible conventions include |
| capitalizing method names, prefixing data attribute names with a small |
| unique string (perhaps just an underscore), or using verbs for methods |
| and nouns for data attributes. |
| |
| |
| Data attributes may be referenced by methods as well as by ordinary |
| users (``clients'') of an object. In other words, classes are not |
| usable to implement pure abstract data types. In fact, nothing in |
| Python makes it possible to enforce data hiding --- it is all based |
| upon convention. (On the other hand, the Python implementation, |
| written in C, can completely hide implementation details and control |
| access to an object if necessary; this can be used by extensions to |
| Python written in C.) |
| |
| |
| Clients should use data attributes with care --- clients may mess up |
| invariants maintained by the methods by stamping on their data |
| attributes. Note that clients may add data attributes of their own to |
| an instance object without affecting the validity of the methods, as |
| long as name conflicts are avoided --- again, a naming convention can |
| save a lot of headaches here. |
| |
| |
| There is no shorthand for referencing data attributes (or other |
| methods!) from within methods. I find that this actually increases |
| the readability of methods: there is no chance of confusing local |
| variables and instance variables when glancing through a method. |
| |
| |
| Conventionally, the first argument of methods is often called |
| \code{self}. This is nothing more than a convention: the name |
| \code{self} has absolutely no special meaning to Python. (Note, |
| however, that by not following the convention your code may be less |
| readable by other Python programmers, and it is also conceivable that |
| a \emph{class browser} program be written which relies upon such a |
| convention.) |
| |
| |
| Any function object that is a class attribute defines a method for |
| instances of that class. It is not necessary that the function |
| definition is textually enclosed in the class definition: assigning a |
| function object to a local variable in the class is also ok. For |
| example: |
| |
| \begin{verbatim} |
| # Function defined outside the class |
| def f1(self, x, y): |
| return min(x, x+y) |
| |
| class C: |
| f = f1 |
| def g(self): |
| return 'hello world' |
| h = g |
| \end{verbatim} |
| |
| Now \code{f}, \code{g} and \code{h} are all attributes of class |
| \class{C} that refer to function objects, and consequently they are all |
| methods of instances of \class{C} --- \code{h} being exactly equivalent |
| to \code{g}. Note that this practice usually only serves to confuse |
| the reader of a program. |
| |
| |
| Methods may call other methods by using method attributes of the |
| \code{self} argument: |
| |
| \begin{verbatim} |
| class Bag: |
| def __init__(self): |
| self.data = [] |
| def add(self, x): |
| self.data.append(x) |
| def addtwice(self, x): |
| self.add(x) |
| self.add(x) |
| \end{verbatim} |
| |
| Methods may reference global names in the same way as ordinary |
| functions. The global scope associated with a method is the module |
| containing the class definition. (The class itself is never used as a |
| global scope!) While one rarely encounters a good reason for using |
| global data in a method, there are many legitimate uses of the global |
| scope: for one thing, functions and modules imported into the global |
| scope can be used by methods, as well as functions and classes defined |
| in it. Usually, the class containing the method is itself defined in |
| this global scope, and in the next section we'll find some good |
| reasons why a method would want to reference its own class! |
| |
| |
| \section{Inheritance \label{inheritance}} |
| |
| Of course, a language feature would not be worthy of the name ``class'' |
| without supporting inheritance. The syntax for a derived class |
| definition looks as follows: |
| |
| \begin{verbatim} |
| class DerivedClassName(BaseClassName): |
| <statement-1> |
| . |
| . |
| . |
| <statement-N> |
| \end{verbatim} |
| |
| The name \class{BaseClassName} must be defined in a scope containing |
| the derived class definition. Instead of a base class name, an |
| expression is also allowed. This is useful when the base class is |
| defined in another module, |
| |
| \begin{verbatim} |
| class DerivedClassName(modname.BaseClassName): |
| \end{verbatim} |
| |
| Execution of a derived class definition proceeds the same as for a |
| base class. When the class object is constructed, the base class is |
| remembered. This is used for resolving attribute references: if a |
| requested attribute is not found in the class, it is searched in the |
| base class. This rule is applied recursively if the base class itself |
| is derived from some other class. |
| |
| There's nothing special about instantiation of derived classes: |
| \code{DerivedClassName()} creates a new instance of the class. Method |
| references are resolved as follows: the corresponding class attribute |
| is searched, descending down the chain of base classes if necessary, |
| and the method reference is valid if this yields a function object. |
| |
| Derived classes may override methods of their base classes. Because |
| methods have no special privileges when calling other methods of the |
| same object, a method of a base class that calls another method |
| defined in the same base class, may in fact end up calling a method of |
| a derived class that overrides it. (For \Cpp{} programmers: all methods |
| in Python are effectively \keyword{virtual}.) |
| |
| An overriding method in a derived class may in fact want to extend |
| rather than simply replace the base class method of the same name. |
| There is a simple way to call the base class method directly: just |
| call \samp{BaseClassName.methodname(self, arguments)}. This is |
| occasionally useful to clients as well. (Note that this only works if |
| the base class is defined or imported directly in the global scope.) |
| |
| |
| \subsection{Multiple Inheritance \label{multiple}} |
| |
| Python supports a limited form of multiple inheritance as well. A |
| class definition with multiple base classes looks as follows: |
| |
| \begin{verbatim} |
| class DerivedClassName(Base1, Base2, Base3): |
| <statement-1> |
| . |
| . |
| . |
| <statement-N> |
| \end{verbatim} |
| |
| The only rule necessary to explain the semantics is the resolution |
| rule used for class attribute references. This is depth-first, |
| left-to-right. Thus, if an attribute is not found in |
| \class{DerivedClassName}, it is searched in \class{Base1}, then |
| (recursively) in the base classes of \class{Base1}, and only if it is |
| not found there, it is searched in \class{Base2}, and so on. |
| |
| (To some people breadth first --- searching \class{Base2} and |
| \class{Base3} before the base classes of \class{Base1} --- looks more |
| natural. However, this would require you to know whether a particular |
| attribute of \class{Base1} is actually defined in \class{Base1} or in |
| one of its base classes before you can figure out the consequences of |
| a name conflict with an attribute of \class{Base2}. The depth-first |
| rule makes no differences between direct and inherited attributes of |
| \class{Base1}.) |
| |
| It is clear that indiscriminate use of multiple inheritance is a |
| maintenance nightmare, given the reliance in Python on conventions to |
| avoid accidental name conflicts. A well-known problem with multiple |
| inheritance is a class derived from two classes that happen to have a |
| common base class. While it is easy enough to figure out what happens |
| in this case (the instance will have a single copy of ``instance |
| variables'' or data attributes used by the common base class), it is |
| not clear that these semantics are in any way useful. |
| |
| |
| \section{Private Variables \label{private}} |
| |
| There is limited support for class-private |
| identifiers. Any identifier of the form \code{__spam} (at least two |
| leading underscores, at most one trailing underscore) is now textually |
| replaced with \code{_classname__spam}, where \code{classname} is the |
| current class name with leading underscore(s) stripped. This mangling |
| is done without regard of the syntactic position of the identifier, so |
| it can be used to define class-private instance and class variables, |
| methods, as well as globals, and even to store instance variables |
| private to this class on instances of \emph{other} classes. Truncation |
| may occur when the mangled name would be longer than 255 characters. |
| Outside classes, or when the class name consists of only underscores, |
| no mangling occurs. |
| |
| Name mangling is intended to give classes an easy way to define |
| ``private'' instance variables and methods, without having to worry |
| about instance variables defined by derived classes, or mucking with |
| instance variables by code outside the class. Note that the mangling |
| rules are designed mostly to avoid accidents; it still is possible for |
| a determined soul to access or modify a variable that is considered |
| private. This can even be useful in special circumstances, such as in |
| the debugger, and that's one reason why this loophole is not closed. |
| (Buglet: derivation of a class with the same name as the base class |
| makes use of private variables of the base class possible.) |
| |
| Notice that code passed to \code{exec}, \code{eval()} or |
| \code{evalfile()} does not consider the classname of the invoking |
| class to be the current class; this is similar to the effect of the |
| \code{global} statement, the effect of which is likewise restricted to |
| code that is byte-compiled together. The same restriction applies to |
| \code{getattr()}, \code{setattr()} and \code{delattr()}, as well as |
| when referencing \code{__dict__} directly. |
| |
| Here's an example of a class that implements its own |
| \method{__getattr__()} and \method{__setattr__()} methods and stores |
| all attributes in a private variable, in a way that works in all |
| versions of Python, including those available before this feature was |
| added: |
| |
| \begin{verbatim} |
| class VirtualAttributes: |
| __vdict = None |
| __vdict_name = locals().keys()[0] |
| |
| def __init__(self): |
| self.__dict__[self.__vdict_name] = {} |
| |
| def __getattr__(self, name): |
| return self.__vdict[name] |
| |
| def __setattr__(self, name, value): |
| self.__vdict[name] = value |
| \end{verbatim} |
| |
| |
| \section{Odds and Ends \label{odds}} |
| |
| Sometimes it is useful to have a data type similar to the Pascal |
| ``record'' or C ``struct'', bundling together a couple of named data |
| items. An empty class definition will do nicely: |
| |
| \begin{verbatim} |
| class Employee: |
| pass |
| |
| john = Employee() # Create an empty employee record |
| |
| # Fill the fields of the record |
| john.name = 'John Doe' |
| john.dept = 'computer lab' |
| john.salary = 1000 |
| \end{verbatim} |
| |
| A piece of Python code that expects a particular abstract data type |
| can often be passed a class that emulates the methods of that data |
| type instead. For instance, if you have a function that formats some |
| data from a file object, you can define a class with methods |
| \method{read()} and \method{readline()} that gets the data from a string |
| buffer instead, and pass it as an argument.% (Unfortunately, this |
| %technique has its limitations: a class can't define operations that |
| %are accessed by special syntax such as sequence subscripting or |
| %arithmetic operators, and assigning such a ``pseudo-file'' to |
| %\code{sys.stdin} will not cause the interpreter to read further input |
| %from it.) |
| |
| |
| Instance method objects have attributes, too: \code{m.im_self} is the |
| object of which the method is an instance, and \code{m.im_func} is the |
| function object corresponding to the method. |
| |
| \subsection{Exceptions Can Be Classes \label{exceptionClasses}} |
| |
| User-defined exceptions are no longer limited to being string objects |
| --- they can be identified by classes as well. Using this mechanism it |
| is possible to create extensible hierarchies of exceptions. |
| |
| There are two new valid (semantic) forms for the raise statement: |
| |
| \begin{verbatim} |
| raise Class, instance |
| |
| raise instance |
| \end{verbatim} |
| |
| In the first form, \code{instance} must be an instance of |
| \class{Class} or of a class derived from it. The second form is a |
| shorthand for: |
| |
| \begin{verbatim} |
| raise instance.__class__, instance |
| \end{verbatim} |
| |
| An except clause may list classes as well as string objects. A class |
| in an except clause is compatible with an exception if it is the same |
| class or a base class thereof (but not the other way around --- an |
| except clause listing a derived class is not compatible with a base |
| class). For example, the following code will print B, C, D in that |
| order: |
| |
| \begin{verbatim} |
| class B: |
| pass |
| class C(B): |
| pass |
| class D(C): |
| pass |
| |
| for c in [B, C, D]: |
| try: |
| raise c() |
| except D: |
| print "D" |
| except C: |
| print "C" |
| except B: |
| print "B" |
| \end{verbatim} |
| |
| Note that if the except clauses were reversed (with |
| \samp{except B} first), it would have printed B, B, B --- the first |
| matching except clause is triggered. |
| |
| When an error message is printed for an unhandled exception which is a |
| class, the class name is printed, then a colon and a space, and |
| finally the instance converted to a string using the built-in function |
| \function{str()}. |
| |
| |
| \chapter{What Now? \label{whatNow}} |
| |
| Reading this tutorial has probably reinforced your interest in using |
| Python --- you should be eager to apply Python to solve your |
| real-world problems. Now what should you do? |
| |
| You should read, or at least page through, the |
| \citetitle[../lib/lib.html]{Python Library Reference}, |
| which gives complete (though terse) reference material about types, |
| functions, and modules that can save you a lot of time when writing |
| Python programs. The standard Python distribution includes a |
| \emph{lot} of code in both C and Python; there are modules to read |
| \UNIX{} mailboxes, retrieve documents via HTTP, generate random |
| numbers, parse command-line options, write CGI programs, compress |
| data, and a lot more; skimming through the Library Reference will give |
| you an idea of what's available. |
| |
| The major Python Web site is \url{http://www.python.org/}; it contains |
| code, documentation, and pointers to Python-related pages around the |
| Web. This Web site is mirrored in various places around the |
| world, such as Europe, Japan, and Australia; a mirror may be faster |
| than the main site, depending on your geographical location. A more |
| informal site is \url{http://starship.python.net/}, which contains a |
| bunch of Python-related personal home pages; many people have |
| downloadable software there. |
| |
| For Python-related questions and problem reports, you can post to the |
| newsgroup \newsgroup{comp.lang.python}, or send them to the mailing |
| list at \email{python-list@python.org}. The newsgroup and mailing list |
| are gatewayed, so messages posted to one will automatically be |
| forwarded to the other. There are around 120 postings a day, |
| % Postings figure based on average of last six months activity as |
| % reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182 |
| % days = 116.9 msgs / day and steadily increasing. |
| asking (and answering) questions, suggesting new features, and |
| announcing new modules. Before posting, be sure to check the list of |
| Frequently Asked Questions (also called the FAQ), at |
| \url{http://www.python.org/doc/FAQ.html}, or look for it in the |
| \file{Misc/} directory of the Python source distribution. Mailing |
| list archives are available at \url{http://www.python.org/pipermail/}. |
| The FAQ answers many of the questions that come up again and again, |
| and may already contain the solution for your problem. |
| |
| |
| \appendix |
| |
| \chapter{Interactive Input Editing and History Substitution |
| \label{interacting}} |
| |
| Some versions of the Python interpreter support editing of the current |
| input line and history substitution, similar to facilities found in |
| the Korn shell and the GNU Bash shell. This is implemented using the |
| \emph{GNU Readline} library, which supports Emacs-style and vi-style |
| editing. This library has its own documentation which I won't |
| duplicate here; however, the basics are easily explained. The |
| interactive editing and history described here are optionally |
| available in the \UNIX{} and CygWin versions of the interpreter. |
| |
| This chapter does \emph{not} document the editing facilities of Mark |
| Hammond's PythonWin package or the Tk-based environment, IDLE, |
| distributed with Python. The command line history recall which |
| operates within DOS boxes on NT and some other DOS and Windows flavors |
| is yet another beast. |
| |
| \section{Line Editing \label{lineEditing}} |
| |
| If supported, input line editing is active whenever the interpreter |
| prints a primary or secondary prompt. The current line can be edited |
| using the conventional Emacs control characters. The most important |
| of these are: \kbd{C-A} (Control-A) moves the cursor to the beginning |
| of the line, \kbd{C-E} to the end, \kbd{C-B} moves it one position to |
| the left, \kbd{C-F} to the right. Backspace erases the character to |
| the left of the cursor, \kbd{C-D} the character to its right. |
| \kbd{C-K} kills (erases) the rest of the line to the right of the |
| cursor, \kbd{C-Y} yanks back the last killed string. |
| \kbd{C-underscore} undoes the last change you made; it can be repeated |
| for cumulative effect. |
| |
| \section{History Substitution \label{history}} |
| |
| History substitution works as follows. All non-empty input lines |
| issued are saved in a history buffer, and when a new prompt is given |
| you are positioned on a new line at the bottom of this buffer. |
| \kbd{C-P} moves one line up (back) in the history buffer, |
| \kbd{C-N} moves one down. Any line in the history buffer can be |
| edited; an asterisk appears in front of the prompt to mark a line as |
| modified. Pressing the \kbd{Return} key passes the current line to |
| the interpreter. \kbd{C-R} starts an incremental reverse search; |
| \kbd{C-S} starts a forward search. |
| |
| \section{Key Bindings \label{keyBindings}} |
| |
| The key bindings and some other parameters of the Readline library can |
| be customized by placing commands in an initialization file called |
| \file{\~{}/.inputrc}. Key bindings have the form |
| |
| \begin{verbatim} |
| key-name: function-name |
| \end{verbatim} |
| |
| or |
| |
| \begin{verbatim} |
| "string": function-name |
| \end{verbatim} |
| |
| and options can be set with |
| |
| \begin{verbatim} |
| set option-name value |
| \end{verbatim} |
| |
| For example: |
| |
| \begin{verbatim} |
| # I prefer vi-style editing: |
| set editing-mode vi |
| |
| # Edit using a single line: |
| set horizontal-scroll-mode On |
| |
| # Rebind some keys: |
| Meta-h: backward-kill-word |
| "\C-u": universal-argument |
| "\C-x\C-r": re-read-init-file |
| \end{verbatim} |
| |
| Note that the default binding for \kbd{Tab} in Python is to insert a |
| \kbd{Tab} character instead of Readline's default filename completion |
| function. If you insist, you can override this by putting |
| |
| \begin{verbatim} |
| Tab: complete |
| \end{verbatim} |
| |
| in your \file{\~{}/.inputrc}. (Of course, this makes it harder to |
| type indented continuation lines.) |
| |
| Automatic completion of variable and module names is optionally |
| available. To enable it in the interpreter's interactive mode, add |
| the following to your startup file:\footnote{ |
| Python will execute the contents of a file identified by the |
| \envvar{PYTHONSTARTUP} environment variable when you start an |
| interactive interpreter.} |
| \refstmodindex{rlcompleter}\refbimodindex{readline} |
| |
| \begin{verbatim} |
| import rlcompleter, readline |
| readline.parse_and_bind('tab: complete') |
| \end{verbatim} |
| |
| This binds the \kbd{Tab} key to the completion function, so hitting |
| the \kbd{Tab} key twice suggests completions; it looks at Python |
| statement names, the current local variables, and the available module |
| names. For dotted expressions such as \code{string.a}, it will |
| evaluate the the expression up to the final \character{.} and then |
| suggest completions from the attributes of the resulting object. Note |
| that this may execute application-defined code if an object with a |
| \method{__getattr__()} method is part of the expression. |
| |
| A more capable startup file might look like this example. Note that |
| this deletes the names it creates once they are no longer needed; this |
| is done since the startup file is executed in the same namespace as |
| the interactive commands, and removing the names avoids creating side |
| effects in the interactive environments. You may find it convenient |
| to keep some of the imported modules, such as \module{os}, which turn |
| out to be needed in most sessions with the interpreter. |
| |
| \begin{verbatim} |
| # Add auto-completion and a stored history file of commands to your Python |
| # interactive interpreter. Requires Python 2.0+, readline. Autocomplete is |
| # bound to the Esc key by default (you can change it - see readline docs). |
| # |
| # Store the file in ~/.pystartup, and set an environment variable to point |
| # to it, e.g. "export PYTHONSTARTUP=/max/home/itamar/.pystartup" in bash. |
| # |
| # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the |
| # full path to your home directory. |
| |
| import atexit |
| import os |
| import readline |
| import rlcompleter |
| |
| historyPath = os.path.expanduser("~/.pyhistory") |
| |
| def save_history(historyPath=historyPath): |
| import readline |
| readline.write_history_file(historyPath) |
| |
| if os.path.exists(historyPath): |
| readline.read_history_file(historyPath) |
| |
| atexit.register(save_history) |
| del os, atexit, readline, rlcompleter, save_history, historyPath |
| \end{verbatim} |
| |
| |
| \section{Commentary \label{commentary}} |
| |
| This facility is an enormous step forward compared to earlier versions |
| of the interpreter; however, some wishes are left: It would be nice if |
| the proper indentation were suggested on continuation lines (the |
| parser knows if an indent token is required next). The completion |
| mechanism might use the interpreter's symbol table. A command to |
| check (or even suggest) matching parentheses, quotes, etc., would also |
| be useful. |
| |
| |
| \chapter{Floating Point Arithmetic: Issues and Limitations |
| \label{fp-issues}} |
| \sectionauthor{Tim Peters}{tim.one@home.com} |
| |
| Floating-point numbers are represented in computer hardware as |
| base 2 (binary) fractions. For example, the decimal fraction |
| |
| \begin{verbatim} |
| 0.125 |
| \end{verbatim} |
| |
| has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction |
| |
| \begin{verbatim} |
| 0.001 |
| \end{verbatim} |
| |
| has value 0/2 + 0/4 + 1/8. These two fractions have identical values, |
| the only real difference being that the first is written in base 10 |
| fractional notation, and the second in base 2. |
| |
| Unfortunately, most decimal fractions cannot be represented exactly as |
| binary fractions. A consequence is that, in general, the decimal |
| floating-point numbers you enter are only approximated by the binary |
| floating-point numbers actually stored in the machine. |
| |
| The problem is easier to understand at first in base 10. Consider the |
| fraction 1/3. You can approximate that as a base 10 fraction: |
| |
| \begin{verbatim} |
| 0.3 |
| \end{verbatim} |
| |
| or, better, |
| |
| \begin{verbatim} |
| 0.33 |
| \end{verbatim} |
| |
| or, better, |
| |
| \begin{verbatim} |
| 0.333 |
| \end{verbatim} |
| |
| and so on. No matter how many digits you're willing to write down, the |
| result will never be exactly 1/3, but will be an increasingly better |
| approximation to 1/3. |
| |
| In the same way, no matter how many base 2 digits you're willing to |
| use, the decimal value 0.1 cannot be represented exactly as a base 2 |
| fraction. In base 2, 1/10 is the infinitely repeating fraction |
| |
| \begin{verbatim} |
| 0.0001100110011001100110011001100110011001100110011... |
| \end{verbatim} |
| |
| Stop at any finite number of bits, and you get an approximation. This |
| is why you see things like: |
| |
| \begin{verbatim} |
| >>> 0.1 |
| 0.10000000000000001 |
| \end{verbatim} |
| |
| On most machines today, that is what you'll see if you enter 0.1 at |
| a Python prompt. You may not, though, because the number of bits |
| used by the hardware to store floating-point values can vary across |
| machines, and Python only prints a decimal approximation to the true |
| decimal value of the binary approximation stored by the machine. On |
| most machines, if Python were to print the true decimal value of |
| the binary approximation stored for 0.1, it would have to display |
| |
| \begin{verbatim} |
| >>> 0.1 |
| 0.1000000000000000055511151231257827021181583404541015625 |
| \end{verbatim} |
| |
| instead! The Python prompt (implicitly) uses the builtin |
| \function{repr()} function to obtain a string version of everything it |
| displays. For floats, \code{repr(\var{float})} rounds the true |
| decimal value to 17 significant digits, giving |
| |
| \begin{verbatim} |
| 0.10000000000000001 |
| \end{verbatim} |
| |
| \code{repr(\var{float})} produces 17 significant digits because it |
| turns out that's enough (on most machines) so that |
| \code{eval(repr(\var{x})) == \var{x}} exactly for all finite floats |
| \var{x}, but rounding to 16 digits is not enough to make that true. |
| |
| Note that this is in the very nature of binary floating-point: this is |
| not a bug in Python, it is not a bug in your code either, and you'll |
| see the same kind of thing in all languages that support your |
| hardware's floating-point arithmetic (although some languages may |
| not \emph{display} the difference by default, or in all output modes). |
| |
| Python's builtin \function{str()} function produces only 12 |
| significant digits, and you may wish to use that instead. It's |
| unusual for \code{eval(str(\var{x}))} to reproduce \var{x}, but the |
| output may be more pleasant to look at: |
| |
| \begin{verbatim} |
| >>> print str(0.1) |
| 0.1 |
| \end{verbatim} |
| |
| It's important to realize that this is, in a real sense, an illusion: |
| the value in the machine is not exactly 1/10, you're simply rounding |
| the \emph{display} of the true machine value. |
| |
| Other surprises follow from this one. For example, after seeing |
| |
| \begin{verbatim} |
| >>> 0.1 |
| 0.10000000000000001 |
| \end{verbatim} |
| |
| you may be tempted to use the \function{round()} function to chop it |
| back to the single digit you expect. But that makes no difference: |
| |
| \begin{verbatim} |
| >>> round(0.1, 1) |
| 0.10000000000000001 |
| \end{verbatim} |
| |
| The problem is that the binary floating-point value stored for "0.1" |
| was already the best possible binary approximation to 1/10, so trying |
| to round it again can't make it better: it was already as good as it |
| gets. |
| |
| Another consequence is that since 0.1 is not exactly 1/10, adding 0.1 |
| to itself 10 times may not yield exactly 1.0, either: |
| |
| \begin{verbatim} |
| >>> sum = 0.0 |
| >>> for i in range(10): |
| ... sum += 0.1 |
| ... |
| >>> sum |
| 0.99999999999999989 |
| \end{verbatim} |
| |
| Binary floating-point arithmetic holds many surprises like this. The |
| problem with "0.1" is explained in precise detail below, in the |
| "Representation Error" section. See |
| \citetitle[http://www.lahey.com/float.htm]{The Perils of Floating |
| Point} for a more complete account of other common surprises. |
| |
| As that says near the end, ``there are no easy answers.'' Still, |
| don't be unduly wary of floating-point! The errors in Python float |
| operations are inherited from the floating-point hardware, and on most |
| machines are on the order of no more than 1 part in 2**53 per |
| operation. That's more than adequate for most tasks, but you do need |
| to keep in mind that it's not decimal arithmetic, and that every float |
| operation can suffer a new rounding error. |
| |
| While pathological cases do exist, for most casual use of |
| floating-point arithmetic you'll see the result you expect in the end |
| if you simply round the display of your final results to the number of |
| decimal digits you expect. \function{str()} usually suffices, and for |
| finer control see the discussion of Pythons's \code{\%} format |
| operator: the \code{\%g}, \code{\%f} and \code{\%e} format codes |
| supply flexible and easy ways to round float results for display. |
| |
| |
| \section{Representation Error |
| \label{fp-error}} |
| |
| This section explains the ``0.1'' example in detail, and shows how |
| you can perform an exact analysis of cases like this yourself. Basic |
| familiarity with binary floating-point representation is assumed. |
| |
| \dfn{Representation error} refers to that some (most, actually) |
| decimal fractions cannot be represented exactly as binary (base 2) |
| fractions. This is the chief reason why Python (or Perl, C, \Cpp, |
| Java, Fortran, and many others) often won't display the exact decimal |
| number you expect: |
| |
| \begin{verbatim} |
| >>> 0.1 |
| 0.10000000000000001 |
| \end{verbatim} |
| |
| Why is that? 1/10 is not exactly representable as a binary fraction. |
| Almost all machines today (November 2000) use IEEE-754 floating point |
| arithmetic, and almost all platforms map Python floats to IEEE-754 |
| "double precision". 754 doubles contain 53 bits of precision, so on |
| input the computer strives to convert 0.1 to the closest fraction it can |
| of the form \var{J}/2**\var{N} where \var{J} is an integer containing |
| exactly 53 bits. Rewriting |
| |
| \begin{verbatim} |
| 1 / 10 ~= J / (2**N) |
| \end{verbatim} |
| |
| as |
| |
| \begin{verbatim} |
| J ~= 2**N / 10 |
| \end{verbatim} |
| |
| and recalling that \var{J} has exactly 53 bits (is \code{>= 2**52} but |
| \code{< 2**53}), the best value for \var{N} is 56: |
| |
| \begin{verbatim} |
| >>> 2L**52 |
| 4503599627370496L |
| >>> 2L**53 |
| 9007199254740992L |
| >>> 2L**56/10 |
| 7205759403792793L |
| \end{verbatim} |
| |
| That is, 56 is the only value for \var{N} that leaves \var{J} with |
| exactly 53 bits. The best possible value for \var{J} is then that |
| quotient rounded: |
| |
| \begin{verbatim} |
| >>> q, r = divmod(2L**56, 10) |
| >>> r |
| 6L |
| \end{verbatim} |
| |
| Since the remainder is more than half of 10, the best approximation is |
| obtained by rounding up: |
| |
| \begin{verbatim} |
| >>> q+1 |
| 7205759403792794L |
| \end{verbatim} |
| |
| Therefore the best possible approximation to 1/10 in 754 double |
| precision is that over 2**56, or |
| |
| \begin{verbatim} |
| 7205759403792794 / 72057594037927936 |
| \end{verbatim} |
| |
| Note that since we rounded up, this is actually a little bit larger than |
| 1/10; if we had not rounded up, the quotient would have been a little |
| bit smaller than 1/10. But in no case can it be \emph{exactly} 1/10! |
| |
| So the computer never ``sees'' 1/10: what it sees is the exact |
| fraction given above, the best 754 double approximation it can get: |
| |
| \begin{verbatim} |
| >>> .1 * 2L**56 |
| 7205759403792794.0 |
| \end{verbatim} |
| |
| If we multiply that fraction by 10**30, we can see the (truncated) |
| value of its 30 most significant decimal digits: |
| |
| \begin{verbatim} |
| >>> 7205759403792794L * 10L**30 / 2L**56 |
| 100000000000000005551115123125L |
| \end{verbatim} |
| |
| meaning that the exact number stored in the computer is approximately |
| equal to the decimal value 0.100000000000000005551115123125. Rounding |
| that to 17 significant digits gives the 0.10000000000000001 that Python |
| displays (well, will display on any 754-conforming platform that does |
| best-possible input and output conversions in its C library --- yours may |
| not!). |
| |
| \chapter{History and License} |
| \input{license} |
| |
| \end{document} |