diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index e1d90551424..6ce6fb0eb59 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -100,7 +100,7 @@ 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 +Python allows you to split 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. Some of these @@ -114,7 +114,7 @@ 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 +Python enables programs to written compactly and readably. Programs written in Python are typically much shorter than equivalent C or \Cpp{} programs, for several reasons: \begin{itemize} @@ -145,7 +145,7 @@ it is encouraged! 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 to do so with this tutorial. +to use it, you are invited to do so with this tutorial. In the next chapter, the mechanics of using the interpreter are explained. This is rather mundane information, but essential for @@ -293,7 +293,7 @@ the stack trace. (Exceptions handled by an \keyword{except} clause in a 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 +normal output from executed commands is written to standard output. Typing the interrupt character (usually Control-C or DEL) to the @@ -1227,7 +1227,7 @@ containing arithmetic progressions: \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 +\code{range(10)} generates a list of 10 values, 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'): @@ -1426,7 +1426,7 @@ 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 +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. @@ -1521,7 +1521,7 @@ 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 "if you put", voltage, "volts through it." print "-- Lovely plumage, the", type print "-- It's", state, "!" \end{verbatim} @@ -1646,7 +1646,7 @@ are not available separately, write the function call with the \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 +programming languages like 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 @@ -1753,8 +1753,8 @@ It is an error if there is no such item. \begin{methoddesc}[list]{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. (The square brackets +no index is specified, \code{a.pop()} removes and returns the last item +in the list. The item is also removed from the list. (The square brackets around the \var{i} in the method signature denote that the parameter is optional, not that you should type square brackets at that position. You will see this notation frequently in the @@ -1857,10 +1857,12 @@ use \method{pop()} with \code{0} as the index. For example: 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: +\samp{filter(\var{function}, \var{sequence})} returns a sequence +consisting of those items from the +sequence for which \code{\var{function}(\var{item})} is true. +If \var{sequence} is a \class{string} or \class{tuple}, the result will +be of the same type; otherwise, it is always a \class{list}. +For example, to compute some primes: \begin{verbatim} >>> def f(x): return x % 2 != 0 and x % 3 != 0 @@ -1974,7 +1976,7 @@ SyntaxError: invalid syntax \end{verbatim} List comprehensions are much more flexible than \function{map()} and can be -applied to functions with more than one argument and to nested functions: +applied to complex expressions and nested functions: \begin{verbatim} >>> [str(round(355/113.0, i)) for i in range(1,6)] @@ -1985,7 +1987,9 @@ applied to functions with more than one argument and to nested functions: \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 +of its value: the \keyword{del} statement. Unlike the \method{pop()}) +method which returns a value, the \keyword{del} keyword is a statement +and 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: @@ -2074,7 +2078,7 @@ is also possible: \end{verbatim} This is called, appropriately enough, \emph{sequence unpacking}. -Sequence unpacking requires that the list of variables on the left +Sequence unpacking requires the list of variables on the left to 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! @@ -2097,12 +2101,12 @@ Here is a brief demonstration: \begin{verbatim} >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana'] ->>> fruits = set(basket) # create a set without duplicates ->>> fruits +>>> fruit = set(basket) # create a set without duplicates +>>> fruit set(['orange', 'pear', 'apple', 'banana']) ->>> 'orange' in fruits # fast membership testing +>>> 'orange' in fruit # fast membership testing True ->>> 'crabgrass' in fruits +>>> 'crabgrass' in fruit False >>> # Demonstrate set operations on unique letters from two words @@ -2133,8 +2137,8 @@ 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 +lists as keys, since lists can be modified in place using methods like +\method{append()} and \method{extend()} or modified with slice and indexed assignments. It is best to think of a dictionary as an unordered set of @@ -2291,7 +2295,7 @@ 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 +Comparisons may be combined using 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 have lower priorities than comparison operators; between them, \code{not} has @@ -2304,9 +2308,9 @@ The Boolean operators \code{and} and \code{or} are so-called left to right, and evaluation stops as soon as the outcome is determined. For example, if \code{A} and \code{C} are true but \code{B} is false, \code{A and B and C} does not evaluate the -expression \code{C}. In general, the return value of a short-circuit -operator, when used as a general value and not as a Boolean, is the -last evaluated argument. +expression \code{C}. When used as a general value and not as a +Boolean, the return value of a short-circuit operator is the last +evaluated argument. It is possible to assign the result of a comparison or other Boolean expression to a variable. For example, @@ -2337,8 +2341,8 @@ 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: +characters. Some examples of comparisons between sequences of the +same type: \begin{verbatim} (1, 2, 3) < (1, 2, 4) @@ -2619,7 +2623,7 @@ C> 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 +The variable \code{sys.path} is a list of strings that determines 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 @@ -2946,8 +2950,9 @@ 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. Reverse quotes -(\code{``}) are equivalent to \function{repr()}, but their use is -discouraged. +(\code{``}) are equivalent to \function{repr()}, but they are no +longer used in modern Python code and will likely not be in future +versions of the language. The \function{str()} function is meant to return representations of values which are fairly human-readable, while \function{repr()} is @@ -3035,7 +3040,7 @@ 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{x.ljust(~n)[:n]}.) +\samp{x.ljust(n)[:n]}.) There is another method, \method{zfill()}, which pads a numeric string on the left with zeros. It understands about plus and @@ -3123,8 +3128,8 @@ mode opens the file in binary mode, so there are also modes like 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 +\ASCII{} text files, but it'll corrupt binary data like that in \file{JPEG} or +\file{EXE} files. Be very careful to use binary mode when reading and writing such files. \subsection{Methods of File Objects \label{fileMethods}} @@ -3367,8 +3372,8 @@ The rest of the line provides detail based on the type of exception and what caused it. 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, +exception happened, in the form of a stack traceback. +In general it contains a stack traceback listing source lines; however, it will not display lines read from standard input. The \citetitle[../lib/module-exceptions.html]{Python Library @@ -3390,7 +3395,7 @@ raising the \exception{KeyboardInterrupt} exception. ... x = int(raw_input("Please enter a number: ")) ... break ... except ValueError: -... print "Oops! That was no valid number. Try again..." +... print "Oops! That was no valid number. Try again..." ... \end{verbatim} @@ -3424,7 +3429,7 @@ 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: +as a parenthesized tuple, for example: \begin{verbatim} ... except (RuntimeError, TypeError, NameError): @@ -3479,7 +3484,7 @@ 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. -The except clause may specify a variable after the exception name (or list). +The except clause may specify a variable after the exception name (or tuple). The variable is bound to an exception instance with the arguments stored in \code{instance.args}. For convenience, the exception instance defines \method{__getitem__} and \method{__str__} so the arguments can @@ -3667,11 +3672,11 @@ 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. +whether 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 (because it would be unclear which -clause should be executed). +clause should be executed first). \chapter{Classes \label{classes}} @@ -3684,7 +3689,7 @@ 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 +base class or classes, and 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 @@ -3806,10 +3811,13 @@ names. If a name is declared global, then all references and assignments go directly to the middle scope containing the module's global names. -Otherwise, all variables found outside of the innermost scope are read-only. +Otherwise, all variables found outside of the innermost scope are read-only +(an attempt to write to such a variable will simply create a \emph{new} +local variable in the innermost scope, leaving the identically named +outer variable unchanged). Usually, the local scope references the local names of the (textually) -current function. Outside of functions, the local scope references +current function. Outside 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. @@ -3873,7 +3881,7 @@ 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 were entered) is +(the one in effect just before the class definition 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). @@ -5309,7 +5317,7 @@ the Korn shell and the GNU Bash shell. This is implemented using the 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. +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, @@ -5541,7 +5549,7 @@ the binary approximation stored for 0.1, it would have to display 0.1000000000000000055511151231257827021181583404541015625 \end{verbatim} -instead! The Python prompt (implicitly) uses the builtin +instead! The Python prompt 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 @@ -5556,7 +5564,7 @@ turns out that's enough (on most machines) so that \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. You'll +not a bug in Python, and it is not a bug in your code either. 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). @@ -5595,8 +5603,8 @@ 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: +Another consequence is that since 0.1 is not exactly 1/10, +summing ten values of 0.1 may not yield exactly 1.0, either: \begin{verbatim} >>> sum = 0.0 @@ -5637,7 +5645,7 @@ 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) +\dfn{Representation error} refers to fact 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 @@ -5672,9 +5680,9 @@ and recalling that \var{J} has exactly 53 bits (is \code{>= 2**52} but \begin{verbatim} >>> 2**52 4503599627370496L ->>> 2L**53 +>>> 2**53 9007199254740992L ->>> 2L**56/10 +>>> 2**56/10 7205759403792793L \end{verbatim} @@ -5683,7 +5691,7 @@ exactly 53 bits. The best possible value for \var{J} is then that quotient rounded: \begin{verbatim} ->>> q, r = divmod(2L**56, 10) +>>> q, r = divmod(2**56, 10) >>> r 6L \end{verbatim} @@ -5711,7 +5719,7 @@ 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 +>>> .1 * 2**56 7205759403792794.0 \end{verbatim} @@ -5719,7 +5727,7 @@ 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 +>>> 7205759403792794 * 10**30 / 2**56 100000000000000005551115123125L \end{verbatim}