Changeset 391 for python/trunk/Doc/tutorial

python/trunk

Property svn:mergeinfo set to
/python/vendor/Python-2.7.6 merged eligible
/python/vendor/current merged eligible

python/trunk/Doc/tutorial/classes.rst

-              r2
+              r391
 *******
+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 C++ 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
+Compared with other programming languages, Python's class mechanism adds classes
+with a minimum of new syntax and semantics.  It is a mixture of the class
+mechanisms found in C++ and Modula-3.  Python classes provide all the standard
+features of Object Oriented Programming: the class inheritance mechanism allows
 multiple base classes, a derived class can override any methods of its 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 data.
+In C++ terminology, all class members (including the data members) are *public*,
+and all member functions are *virtual*.  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.  This provides semantics for importing and renaming.  Unlike C++ and
+Modula-3, built-in types can be used as base classes for extension by the user.
+Also, like in C++, most built-in operators with special syntax (arithmetic
+operators, subscripting etc.) can be redefined for class instances.
+name.  Objects can contain arbitrary amounts and kinds of data.  As is true for
+modules, classes partake of the dynamic nature of Python: they are created at
+runtime, and can be modified further after creation.
+In C++ terminology, normally class members (including the data members) are
+*public* (except see below :ref:`tut-private`), and all member functions are
+*virtual*.  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.  This provides semantics for
+importing and renaming.  Unlike C++ and Modula-3, built-in types can be used as
+base classes for extension by the user.  Also, like in C++, most built-in
+operators with special syntax (arithmetic operators, subscripting etc.) can be
+redefined for class instances.
 (Lacking universally accepted terminology to talk about classes, I will make
 …
 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 :func:`abs`, and
+namespaces are: the set of built-in names (containing functions such as :func:`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
 …
 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
+global scope associated with a method is the module containing its
+definition.  (A class 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
 …
 With new-style classes, dynamic ordering is necessary because all  cases of
 multiple inheritance exhibit one or more diamond relationships (where one at
+multiple inheritance exhibit one or more diamond relationships (where at
 least one of the parent classes can be accessed through multiple paths from the
 bottommost class).  For example, all new-style classes inherit from
 …
 .. _tut-private:
 Private Variables
 =================
+Private Variables and Class-local References
+============================================
 "Private" instance variables that cannot be accessed except from inside an
 object, don't exist in Python.  However, there is a convention that is followed
+object don't exist in Python.  However, there is a convention that is followed
 by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
 be treated as a non-public part of the API (whether it is a function, a method
 …
 occurs within the definition of a class.
+Name mangling is helpful for letting subclasses override methods without
+breaking intraclass method calls.  For example::
+   class Mapping:
+       def __init__(self, iterable):
+           self.items_list = []
+           self.__update(iterable)
+       def update(self, iterable):
+           for item in iterable:
+               self.items_list.append(item)
+       __update = update   # private copy of original update() method
+   class MappingSubclass(Mapping):
+       def update(self, keys, values):
+           # provides new signature for update()
+           # but does not break __init__()
+           for item in zip(keys, values):
+               self.items_list.append(item)
 Note that the mangling rules are designed mostly to avoid accidents; it still is
 possible to access or modify a variable that is considered private.  This can
 …
 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 :meth:`read` and :meth:`readline` that get the
+can define a class with methods :meth:`read` and :meth:`!readline` that get the
 data from a string buffer instead, and pass it as an argument.
 …
        print char
    for line in open("myfile.txt"):
        print line
+       print line,
 This style of access is clear, concise, and convenient.  The use of iterators
 pervades and unifies Python.  Behind the scenes, the :keyword:`for` statement
 calls :func:`iter` on the container object.  The function returns an iterator
+object that defines the method :meth:`next` which accesses elements in the
+container one at a time.  When there are no more elements, :meth:`next` raises a
+:exc:`StopIteration` exception which tells the :keyword:`for` loop to terminate.
+object that defines the method :meth:`~iterator.next` which accesses elements
+in the container one at a time.  When there are no more elements,
+:meth:`~iterator.next` raises a :exc:`StopIteration` exception which tells the
+:keyword:`for` loop to terminate.
 This example shows how it all works::
 …
    'c'
    >>> it.next()
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
 …
 Having seen the mechanics behind the iterator protocol, it is easy to add
 iterator behavior to your classes.  Define a :meth:`__iter__` method which
+iterator behavior to your classes.  Define an :meth:`__iter__` method which
 returns an object with a :meth:`next` method.  If the class defines
 :meth:`next`, then :meth:`__iter__` can just return ``self``::
    class Reverse:
        "Iterator for looping over a sequence backwards"
+       """Iterator for looping over a sequence backwards."""
        def __init__(self, data):
            self.data = data
 …
            return self.data[self.index]
+   >>> for char in Reverse('spam'):
+::
+   >>> rev = Reverse('spam')
+   >>> iter(rev)
+   <__main__.Reverse object at 0x00A1DB50>
+   >>> for char in rev:
    ...     print char
    ...
 …
        for index in range(len(data)-1, -1, -1):
            yield data[index]
+::
    >>> for char in reverse('golf'):

python/trunk/Doc/tutorial/controlflow.rst

-              r2
+              r391
    >>> # Measure some strings:
    ... a = ['cat', 'window', 'defenestrate']
    >>> for x in a:
    ...     print x, len(x)
+   ... words = ['cat', 'window', 'defenestrate']
+   >>> for w in words:
+   ...     print w, len(w)
    ...
    cat 3
 …
    defenestrate 12
 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::
    >>> for x in a[:]: # make a slice copy of the entire list
    ...    if len(x) > 6: a.insert(0, x)
    ...
    >>> a
+If you need to modify the sequence you are iterating over while inside the loop
+(for example to duplicate selected items), it is recommended that you first
+make a copy.  Iterating over a sequence does not implicitly make a copy.  The
+slice notation makes this especially convenient::
+   >>> for w in words[:]:  # Loop over a slice copy of the entire list.
+   ...     if len(w) > 6:
+   ...         words.insert(0, w)
+   ...
+   >>> words
    ['defenestrate', 'cat', 'window', 'defenestrate']
 …
 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 ``else`` clause; it is executed when the loop
 …
 equals 2 * 4
 equals 3 * 3
+(Yes, this is the correct code.  Look closely: the ``else`` clause belongs to
+the :keyword:`for` loop, **not** the :keyword:`if` statement.)
+When used with a loop, the ``else`` clause has more in common with the
+``else`` clause of a :keyword:`try` statement than it does that of
+:keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
+when no exception occurs, and a loop's ``else`` clause runs when no ``break``
+occurs. For more on the :keyword:`try` statement and exceptions, see
+:ref:`tut-handling`.
+The :keyword:`continue` statement, also borrowed from C, continues with the next
+iteration of the loop::
+    >>> for num in range(2, 10):
+    ...     if num % 2 == 0:
+    ...         print "Found an even number", num
+    ...         continue
+    ...     print "Found a number", num
+    Found an even number 2
+    Found a number 3
+    Found an even number 4
+    Found a number 5
+    Found an even number 6
+    Found a number 7
+    Found an even number 8
+    Found a number 9
 …
 -----------------
 Functions can also be called using keyword arguments of the form ``keyword =
 value``.  For instance, the following function::
+Functions can also be called using :term:`keyword arguments <keyword argument>`
+of the form ``kwarg=value``.  For instance, the following function::
    def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
 …
        print "-- It's", state, "!"
+could be called in any of the following ways::
+   parrot(1000)
+   parrot(action = 'VOOOOOM', voltage = 1000000)
+   parrot('a thousand', state = 'pushing up the daisies')
+   parrot('a million', 'bereft of life', 'jump')
+but the following calls would all be invalid::
+accepts one required argument (``voltage``) and three optional arguments
+(``state``, ``action``, and ``type``).  This function can be called in any
+of the following ways::
+   parrot(1000)                                          # 1 positional argument
+   parrot(voltage=1000)                                  # 1 keyword argument
+   parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
+   parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
+   parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
+   parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword
+but all the following calls would be invalid::
    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
+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::
+   parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
+   parrot(110, voltage=220)     # duplicate value for the same argument
+   parrot(actor='John Cleese')  # unknown keyword argument
+In a function call, keyword arguments must follow positional arguments.
+All the keyword arguments passed must match one of the arguments
+accepted by the function (e.g. ``actor`` is not a valid argument for the
+``parrot`` function), and their order is not important.  This also includes
+non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
+No argument may receive a value more than once.
+Here's an example that fails due to this restriction::
    >>> def function(a):
 …
        print "-- Do you have any", kind, "?"
        print "-- I'm sorry, we're all out of", kind
+       for arg in arguments: print arg
+       for arg in arguments:
+           print arg
        print "-" * 40
        keys = keywords.keys()
        keys.sort()
        for kw in keys: print kw, ":", keywords[kw]
+       keys = sorted(keywords.keys())
+       for kw in keys:
+           print kw, ":", keywords[kw]
 It could be called like this::
 …
    sketch : Cheese Shop Sketch
+Note that the :meth:`sort` method of the list of keyword argument names is
+called before printing the contents of the ``keywords`` dictionary; if this is
+not done, the order in which the arguments are printed is undefined.
+Note that the list of keyword argument names is created by sorting the result
+of the keywords dictionary's ``keys()`` method before printing its contents;
+if this is not done, the order in which the arguments are printed is undefined.
 .. _tut-arbitraryargs:
 …
 .. _tut-lambda:
+Lambda Forms
+------------
+By popular demand, a few features commonly found in functional 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: ``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::
+Lambda Expressions
+------------------
+Small anonymous functions can be created with the :keyword:`lambda` keyword.
+This function returns the sum of its two arguments: ``lambda a, b: a+b``.
+Lambda functions 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 functions can reference variables from the containing
+scope::
    >>> def make_incrementor(n):
 …
    >>> f(1)
+The above example uses a lambda expression to return a function.  Another use
+is to pass a small function as an argument::
+   >>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
+   >>> pairs.sort(key=lambda pair: pair[1])
+   >>> pairs
+   [(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

python/trunk/Doc/tutorial/datastructures.rst

-              r2
+              r391
 the sequence for which ``function(item)`` is true. If *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::
+otherwise, it is always a :class:`list`. For example, to compute a sequence of
+numbers not divisible by 2 or 3::
    >>> def f(x): return x % 2 != 0 and x % 3 != 0
 …
 and works exactly like this.
+.. versionadded:: 2.3
+.. _tut-listcomps:
 List Comprehensions
 -------------------
+List comprehensions provide a concise way to create lists without resorting to
+use of :func:`map`, :func:`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 followed 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. ::
+List comprehensions provide a concise way to create lists.
+Common applications are to make new lists where each element is the result of
+some operations applied to each member of another sequence or iterable, or to
+create a subsequence of those elements that satisfy a certain condition.
+For example, assume we want to create a list of squares, like::
+   >>> squares = []
+   >>> for x in range(10):
+   ...     squares.append(x**2)
+   ...
+   >>> squares
+   [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
+We can obtain the same result with::
+   squares = [x**2 for x in range(10)]
+This is also equivalent to ``squares = map(lambda x: x**2, range(10))``,
+but it's more concise and readable.
+A list comprehension consists of brackets containing an expression followed
+by a :keyword:`for` clause, then zero or more :keyword:`for` or :keyword:`if`
+clauses.  The result will be a new list resulting from evaluating the expression
+in the context of the :keyword:`for` and :keyword:`if` clauses which follow it.
+For example, this listcomp combines the elements of two lists if they are not
+equal::
+   >>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
+   [(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
+and it's equivalent to:
+   >>> combs = []
+   >>> for x in [1,2,3]:
+   ...     for y in [3,1,4]:
+   ...         if x != y:
+   ...             combs.append((x, y))
+   ...
+   >>> combs
+   [(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
+Note how the order of the :keyword:`for` and :keyword:`if` statements is the
+same in both these snippets.
+If the expression is a tuple (e.g. the ``(x, y)`` in the previous example),
+it must be parenthesized. ::
+   >>> vec = [-4, -2, 0, 2, 4]
+   >>> # create a new list with the values doubled
+   >>> [x*2 for x in vec]
+   [-8, -4, 0, 4, 8]
+   >>> # filter the list to exclude negative numbers
+   >>> [x for x in vec if x >= 0]
+   [0, 2, 4]
+   >>> # apply a function to all the elements
+   >>> [abs(x) for x in vec]
+   [4, 2, 0, 2, 4]
+   >>> # call a method on each element
    >>> 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]  # error - parens required for tuples
+     File "<stdin>", line 1, in ?
+       [x, x**2 for x in vec]
+   >>> # create a list of 2-tuples like (number, square)
+   >>> [(x, x**2) for x in range(6)]
+   [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
+   >>> # the tuple must be parenthesized, otherwise an error is raised
+   >>> [x, x**2 for x in range(6)]
+     File "<stdin>", line 1
+       [x, x**2 for x in range(6)]
+                  ^
    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]
+List comprehensions are much more flexible than :func:`map` and can be applied
+to complex expressions and nested functions::
+   >>> [str(round(355/113.0, i)) for i in range(1,6)]
+   >>> # flatten a list using a listcomp with two 'for'
+   >>> vec = [[1,2,3], [4,5,6], [7,8,9]]
+   >>> [num for elem in vec for num in elem]
+   [1, 2, 3, 4, 5, 6, 7, 8, 9]
+List comprehensions can contain complex expressions and nested functions::
+   >>> from math import pi
+   >>> [str(round(pi, i)) for i in range(1, 6)]
    ['3.1', '3.14', '3.142', '3.1416', '3.14159']
 Nested List Comprehensions
+--------------------------
+If you've got the stomach for it, list comprehensions can be nested. They are a
+powerful tool but -- like all powerful tools -- they need to be used carefully,
+if at all.
+Consider the following example of a 3x3 matrix held as a list containing three
+lists, one list per row::
+    >>> mat = [
+    ...        [1, 2, 3],
+    ...        [4, 5, 6],
+    ...        [7, 8, 9],
+    ...       ]
+Now, if you wanted to swap rows and columns, you could use a list
+comprehension::
+    >>> print [[row[i] for row in mat] for i in [0, 1, 2]]
+    [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
+Special care has to be taken for the *nested* list comprehension:
+    To avoid apprehension when nesting list comprehensions, read from right to
+    left.
+A more verbose version of this snippet shows the flow explicitly::
+    for i in [0, 1, 2]:
+        for row in mat:
+            print row[i],
+        print
+In real world, you should prefer built-in functions to complex flow statements.
+''''''''''''''''''''''''''
+The initial expression in a list comprehension can be any arbitrary expression,
+including another list comprehension.
+Consider the following example of a 3x4 matrix implemented as a list of
+lists of length 4::
+   >>> matrix = [
+   ...     [1, 2, 3, 4],
+   ...     [5, 6, 7, 8],
+   ...     [9, 10, 11, 12],
+   ... ]
+The following list comprehension will transpose rows and columns::
+   >>> [[row[i] for row in matrix] for i in range(4)]
+   [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
+As we saw in the previous section, the nested listcomp is evaluated in
+the context of the :keyword:`for` that follows it, so this example is
+equivalent to::
+   >>> transposed = []
+   >>> for i in range(4):
+   ...     transposed.append([row[i] for row in matrix])
+   ...
+   >>> transposed
+   [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
+which, in turn, is the same as::
+   >>> transposed = []
+   >>> for i in range(4):
+   ...     # the following 3 lines implement the nested listcomp
+   ...     transposed_row = []
+   ...     for row in matrix:
+   ...         transposed_row.append(row[i])
+   ...     transposed.append(transposed_row)
+   ...
+   >>> transposed
+   [[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
+In the real world, you should prefer built-in functions to complex flow statements.
 The :func:`zip` function would do a great job for this use case::
     >>> zip(*mat)
     [(1, 4, 7), (2, 5, 8), (3, 6, 9)]
+   >>> zip(*matrix)
+   [(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
 See :ref:`tut-unpacking-arguments` for details on the asterisk in this line.
 …
    >>> u
    ((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
+   >>> # Tuples are immutable:
+   ... t[0] = 88888
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   TypeError: 'tuple' object does not support item assignment
+   >>> # but they can contain mutable objects:
+   ... v = ([1, 2, 3], [3, 2, 1])
+   >>> v
+   ([1, 2, 3], [3, 2, 1])
 As you see, on output tuples are always 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.
+part of a larger expression).  It is not possible to assign to the individual
+items of a tuple, however it is possible to create tuples which contain mutable
+objects, such as lists.
+Though tuples may seem similar to lists, they are often used in different
+situations and for different purposes.
+Tuples are :term:`immutable`, and usually contain an heterogeneous sequence of
+elements that are accessed via unpacking (see later in this section) or indexing
+(or even by attribute in the case of :func:`namedtuples <collections.namedtuple>`).
+Lists are :term:`mutable`, and their elements are usually homogeneous and are
+accessed by iterating over the list.
 A special problem is the construction of tuples containing 0 or 1 items: the
 …
 packing and sequence unpacking.
-.. XXX Add a bit on the difference between tuples and lists.
 .. _tut-sets:
 …
 eliminating duplicate entries.  Set objects also support mathematical operations
 like union, intersection, difference, and symmetric difference.
+Curly braces or the :func:`set` function can be used to create sets.  Note: to
+create an empty set you have to use ``set()``, not ``{}``; the latter creates an
+empty dictionary, a data structure that we discuss in the next section.
 Here is a brief demonstration::
 …
    set(['r', 'd', 'b', 'm', 'z', 'l'])
+Similarly to :ref:`list comprehensions <tut-listcomps>`, set comprehensions
+are also supported::
+   >>> a = {x for x in 'abracadabra' if x not in 'abc'}
+   >>> a
+   set(['r', 'd'])
 .. _tut-dictionaries:
 …
 The :meth:`keys` method of a dictionary object returns a list of all the keys
 used in the dictionary, in arbitrary order (if you want it sorted, just apply
 the :meth:`sort` method to the list of keys).  To check whether a single key is
 in the dictionary, use the :keyword:`in` keyword.
+the :func:`sorted` function to it).  To check whether a single key is in the
+dictionary, use the :keyword:`in` keyword.
 Here is a small example using a dictionary::
 …
    True
+The :func:`dict` constructor builds dictionaries directly from lists of
+key-value pairs stored as tuples.  When the pairs form a pattern, list
+comprehensions can compactly specify the key-value list. ::
+The :func:`dict` constructor builds dictionaries directly from sequences of
+key-value pairs::
    >>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
    {'sape': 4139, 'jack': 4098, 'guido': 4127}
+   >>> dict([(x, x**2) for x in (2, 4, 6)])     # use a list comprehension
+In addition, dict comprehensions can be used to create dictionaries from
+arbitrary key and value expressions::
+   >>> {x: x**2 for x in (2, 4, 6)}
    {2: 4, 4: 16, 6: 36}
-Later in the tutorial, we will learn about Generator Expressions which are even
-better suited for the task of supplying key-values pairs to the :func:`dict`
-constructor.
 When the keys are simple strings, it is sometimes easier to specify pairs using
 …
 Looping Techniques
 ==================
-When looping through dictionaries, the key and corresponding value can be
-retrieved at the same time using the :meth:`iteritems` method. ::
-   >>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
-   >>> for k, v in knights.iteritems():
-   ...     print k, v
-   ...
-   gallahad the pure
-   robin the brave
 When looping through a sequence, the position index and corresponding value can
 …
    orange
    pear
+When looping through dictionaries, the key and corresponding value can be
+retrieved at the same time using the :meth:`iteritems` method. ::
+   >>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
+   >>> for k, v in knights.iteritems():
+   ...     print k, v
+   ...
+   gallahad the pure
+   robin the brave
+To change a sequence you are iterating over while inside the loop (for
+example to duplicate certain items), it is recommended that you first make
+a copy.  Looping over a sequence does not implicitly make a copy.  The slice
+notation makes this especially convenient::
+   >>> words = ['cat', 'window', 'defenestrate']
+   >>> for w in words[:]:  # Loop over a slice copy of the entire list.
+   ...     if len(w) > 6:
+   ...         words.insert(0, w)
+   ...
+   >>> words
+   ['defenestrate', 'cat', 'window', 'defenestrate']

python/trunk/Doc/tutorial/errors.rst

-              r2
+              r391
    ...     pass
+Note that the parentheses around this tuple are required, because
+``except ValueError, e:`` was the syntax used for what is normally
+written as ``except ValueError as e:`` in modern Python (described
+below). The old syntax is still supported for backwards compatibility.
+This means ``except RuntimeError, TypeError`` is not equivalent to
+``except (RuntimeError, TypeError):`` but to ``except RuntimeError as
+TypeError:`` which is not what you want.
 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
 …
        s = f.readline()
        i = int(s.strip())
    except IOError as (errno, strerror):
        print "I/O error({0}): {1}".format(errno, strerror)
+   except IOError as e:
+       print "I/O error({0}): {1}".format(e.errno, e.strerror)
    except ValueError:
        print "Could not convert data to an integer."
 …
    ...    print inst.args      # arguments stored in .args
    ...    print inst           # __str__ allows args to printed directly
    ...    x, y = inst          # __getitem__ allows args to be unpacked directly
+   ...    x, y = inst.args
    ...    print 'x =', x
    ...    print 'y =', y
 …
    NameError: HiThere
+The argument to :keyword:`raise` is an exception class or instance to be
+raised.  There is a deprecated alternate syntax that separates class and
+constructor arguments; the above could be written as ``raise NameError,
+'HiThere'``.  Since it once was the only one available, the latter form is
+prevalent in older code.
+The sole argument to :keyword:`raise` indicates the exception to be raised.
+This must be either an exception instance or an exception class (a class that
+derives from :class:`Exception`).
 If you need to determine whether an exception was raised but don't intend to
 …
    for line in open("myfile.txt"):
        print line
+       print line,
 The problem with this code is that it leaves the file open for an indeterminate
 …
    with open("myfile.txt") as f:
        for line in f:
            print line
+           print line,
 After the statement is executed, the file *f* is always closed, even if a

python/trunk/Doc/tutorial/floatingpoint.rst

-              r2
+              r391
 .0001100110011001100110011001100110011001100110011...
+Stop at any finite number of bits, and you get an approximation.  This is why
+you see things like::
+   >>> 0.1
+.10000000000000001
+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 ::
+Stop at any finite number of bits, and you get an approximation.
+On a typical machine running Python, there are 53 bits of precision available
+for a Python float, so the value stored internally when you enter the decimal
+number ``0.1`` is the binary fraction ::
+.00011001100110011001100110011001100110011001100110011010
+which is close to, but not exactly equal to, 1/10.
+It's easy to forget that the stored value is an approximation to the original
+decimal fraction, because of the way that floats are displayed at the
+interpreter prompt.  Python only prints a decimal approximation to the true
+decimal value of the binary approximation stored by the machine.  If Python
+were to print the true decimal value of the binary approximation stored for
+.1, it would have to display ::
    >>> 0.1
 .1000000000000000055511151231257827021181583404541015625
+instead!  The Python prompt uses the built-in :func:`repr` function to obtain a
+string version of everything it displays.  For floats, ``repr(float)`` rounds
+the true decimal value to 17 significant digits, giving ::
+.10000000000000001
+``repr(float)`` produces 17 significant digits because it turns out that's
+enough (on most machines) so that ``eval(repr(x)) == x`` exactly for all finite
+floats *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, 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 *display* the difference by default, or in all
+output modes).
+Python's built-in :func:`str` function produces only 12 significant digits, and
+you may wish to use that instead.  It's unusual for ``eval(str(x))`` to
+reproduce *x*, but the output may be more pleasant to look at::
+   >>> print str(0.1)
+That is more digits than most people find useful, so Python keeps the number
+of digits manageable by displaying a rounded value instead ::
+   >>> 0.1
 .1
 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 *display* of the
+true machine value.
+Other surprises follow from this one.  For example, after seeing ::
+   >>> 0.1
+.10000000000000001
+you may be tempted to use the :func:`round` function to chop it back to the
+single digit you expect.  But that makes no difference::
+   >>> round(0.1, 1)
+.10000000000000001
+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, summing ten values of
+.1 may not yield exactly 1.0, either::
+true machine value.  This fact becomes apparent as soon as you try to do
+arithmetic with these values ::
+   >>> 0.1 + 0.2
+.30000000000000004
+Note that this is in the very nature of binary floating-point: this is 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 *display* the difference by
+default, or in all output modes).
+Other surprises follow from this one.  For example, if you try to round the
+value 2.675 to two decimal places, you get this ::
+   >>> round(2.675, 2)
+.67
+The documentation for the built-in :func:`round` function says that it rounds
+to the nearest value, rounding ties away from zero.  Since the decimal fraction
+.675 is exactly halfway between 2.67 and 2.68, you might expect the result
+here to be (a binary approximation to) 2.68.  It's not, because when the
+decimal string ``2.675`` is converted to a binary floating-point number, it's
+again replaced with a binary approximation, whose exact value is ::
+.67499999999999982236431605997495353221893310546875
+Since this approximation is slightly closer to 2.67 than to 2.68, it's rounded
+down.
+If you're in a situation where you care which way your decimal halfway-cases
+are rounded, you should consider using the :mod:`decimal` module.
+Incidentally, the :mod:`decimal` module also provides a nice way to "see" the
+exact value that's stored in any particular Python float ::
+   >>> from decimal import Decimal
+   >>> Decimal(2.675)
+   Decimal('2.67499999999999982236431605997495353221893310546875')
+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::
    >>> sum = 0.0
 …
    ...
    >>> sum
 .99999999999999989
+.9999999999999999
 Binary floating-point arithmetic holds many surprises like this.  The problem
 …
 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.
+:func:`str` usually suffices, and for finer control see the :meth:`str.format`
 method's format specifiers in :ref:`formatstrings`.
+display of your final results to the number of decimal digits you expect.  For
+fine control over how a float is displayed see the :meth:`str.format` method's
+format specifiers in :ref:`formatstrings`.
 …
 ====================
 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.
+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 the fact that some (most, actually)
 …
 others) often won't display the exact decimal number you expect::
    >>> 0.1
 .10000000000000001
 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 *J*/2**\ *N* where *J* is
 an integer containing exactly 53 bits.  Rewriting ::
+   >>> 0.1 + 0.2
+.30000000000000004
+Why is that?  1/10 and 2/10 are not exactly representable as a binary
+fraction. Almost all machines today (July 2010) 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 *J*/2**\ *N*
+where *J* is an integer containing exactly 53 bits.  Rewriting ::
 / 10 ~= J / (2**N)
 …
    >>> 2**52
    4503599627370496L
+   4503599627370496
    >>> 2**53
    9007199254740992L
+   9007199254740992
    >>> 2**56/10
    7205759403792793L
 That is, 56 is the only value for *N* that leaves *J* with exactly 53 bits.  The
 best possible value for *J* is then that quotient rounded::
+   7205759403792793
+That is, 56 is the only value for *N* that leaves *J* with exactly 53 bits.
+The best possible value for *J* is then that quotient rounded::
    >>> q, r = divmod(2**56, 10)
    >>> r
 L
 Since the remainder is more than half of 10, the best approximation is obtained
 …
    >>> q+1
    7205759403792794L
+   7205759403792794
 Therefore the best possible approximation to 1/10 in 754 double precision is
 …
 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
 /10.  But in no case can it be *exactly* 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 *exactly* 1/10!
 So the computer never "sees" 1/10:  what it sees is the exact fraction given
 …
 its 30 most significant decimal digits::
    >>> 7205759403792794 * 10**30 / 2**56
+   >>> 7205759403792794 * 10**30 // 2**56
    100000000000000005551115123125L
 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!).
+the decimal value 0.100000000000000005551115123125.  In versions prior to
+Python 2.7 and Python 3.1, Python rounded this value to 17 significant digits,
+giving '0.10000000000000001'.  In current versions, Python displays a value
+based on the shortest decimal fraction that rounds correctly back to the true
+binary value, resulting simply in '0.1'.

python/trunk/Doc/tutorial/index.rst

-              r2
+              r391
   The Python Tutorial
 ######################
-:Release: |version|
-:Date: |today|
 Python is an easy to learn, powerful programming language. It has efficient

python/trunk/Doc/tutorial/inputoutput.rst

-              r2
+              r391
 See the Library Reference for more information on this.)
-.. index:: module: string
 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 layout you can imagine.  The
 standard module :mod:`string` contains some useful operations for padding
+string types have some methods that perform useful operations for padding
 strings to a given column width; these will be discussed shortly.  The second
 way is to use the :meth:`str.format` method.
+The :mod:`string` module contains a :class:`~string.Template` class which offers
+yet another way to substitute values into strings.
 One question remains, of course: how do you convert values to strings? Luckily,
 …
 fairly human-readable, while :func:`repr` is meant to generate representations
 which can be read by the interpreter (or will force a :exc:`SyntaxError` if
 there is not equivalent syntax).  For objects which don't have a particular
+there is no equivalent syntax).  For objects which don't have a particular
 representation for human consumption, :func:`str` will return the same value as
 :func:`repr`.  Many values, such as numbers or structures like lists and
 …
    >>> repr(s)
    "'Hello, world.'"
    >>> str(0.1)
    '0.1'
    >>> repr(0.1)
    '0.10000000000000001'
+   >>> str(1.0/7.0)
+   '0.142857142857'
+   >>> repr(1.0/7.0)
+   '0.14285714285714285'
    >>> x = 10 * 3.25
    >>> y = 200 * 200
 …
 way :keyword:`print` works: it always adds spaces between its arguments.)
+This example demonstrates the :meth:`rjust` method of string objects, which
+right-justifies a string in a field of a given width by padding it with spaces
+on the left.  There are similar methods :meth:`ljust` and :meth:`center`.  These
+methods 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 ``x.ljust(n)[:n]``.)
+There is another method, :meth:`zfill`, which pads a numeric string on the left
+with zeros.  It understands about plus and minus signs::
+This example demonstrates the :meth:`str.rjust` method of string
+objects, which right-justifies a string in a field of a given width by padding
+it with spaces on the left.  There are similar methods :meth:`str.ljust` and
+:meth:`str.center`.  These methods 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
+``x.ljust(n)[:n]``.)
+There is another method, :meth:`str.zfill`, which pads a numeric string on the
+left with zeros.  It understands about plus and minus signs::
    >>> '12'.zfill(5)
 …
 Basic usage of the :meth:`str.format` method looks like this::
    >>> print 'We are the {0} who say "{1}!"'.format('knights', 'Ni')
+   >>> print 'We are the {} who say "{}!"'.format('knights', 'Ni')
    We are the knights who say "Ni!"
 The brackets and characters within them (called format fields) are replaced with
 the objects passed into the :meth:`~str.format` method.  A number in the
+the objects passed into the :meth:`str.format` method.  A number in the
 brackets refers to the position of the object passed into the
 :meth:`~str.format` method. ::
+:meth:`str.format` method. ::
    >>> print '{0} and {1}'.format('spam', 'eggs')
 …
    eggs and spam
 If keyword arguments are used in the :meth:`~str.format` method, their values
+If keyword arguments are used in the :meth:`str.format` method, their values
 are referred to by using the name of the argument. ::
 …
    >>> import math
    >>> print 'The value of PI is approximately {0}.'.format(math.pi)
+   >>> print 'The value of PI is approximately {}.'.format(math.pi)
    The value of PI is approximately 3.14159265359.
    >>> print 'The value of PI is approximately {0!r}.'.format(math.pi)
+   >>> print 'The value of PI is approximately {!r}.'.format(math.pi)
    The value of PI is approximately 3.141592653589793.
 An optional ``':'`` and format specifier can follow the field name. This allows
 greater control over how the value is formatted.  The following example
 truncates Pi to three places after the decimal.
+rounds Pi to three places after the decimal.
    >>> import math
 …
    Jack: 4098; Sjoerd: 4127; Dcab: 8637678
 This is particularly useful in combination with the new built-in :func:`vars`
 function, which returns a dictionary containing all local variables.
+This is particularly useful in combination with the built-in function
+:func:`vars`, which returns a dictionary containing all local variables.
 For a complete overview of string formatting with :meth:`str.format`, see
 …
 The ``%`` operator can also be used for string formatting. It interprets the
 left argument much like a :cfunc:`sprintf`\ -style format string to be applied
+left argument much like a :c:func:`sprintf`\ -style format string to be applied
 to the right argument, and returns the string resulting from this formatting
 operation. For example::
 …
    The value of PI is approximately 3.142.
-Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
-operator. However, because this old style of formatting will eventually be
-removed from the language, :meth:`str.format` should generally be used.
 More information can be found in the :ref:`string-formatting` section.
 …
 ::
    >>> f = open('/tmp/workfile', 'w')
+   >>> f = open('workfile', 'w')
    >>> print f
    <open file '/tmp/workfile', mode 'w' at 80a0960>
+   <open file 'workfile', mode 'w' at 80a0960>
 The first argument is a string containing the filename.  The second argument is
 …
    ''
+``f.readlines()`` returns a list containing all the lines of data in the file.
+If given an optional parameter *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.
+::
+   >>> f.readlines()
+   ['This is the first line of the file.\n', 'Second line of the file\n']
+An alternative approach to reading lines is to loop over the file object. This is
+memory efficient, fast, and leads to simpler code::
+For reading lines from a file, you can loop over the file object. This is memory
+efficient, fast, and leads to simple code::
    >>> for line in f:
 …
    Second line of the file
+The alternative approach is simpler but does not provide as fine-grained
+control.  Since the two approaches manage line buffering differently, they
+should not be mixed.
+If you want to read all the lines of a file in a list you can also use
+``list(f)`` or ``f.readlines()``.
 ``f.write(string)`` writes the contents of *string* to the file, returning
 …
 beginning of the file as the reference point. ::
    >>> f = open('/tmp/workfile', 'r+')
+   >>> f = open('workfile', 'r+')
    >>> f.write('0123456789abcdef')
    >>> f.seek(5)     # Go to the 6th byte in the file
 …
 shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
     >>> with open('/tmp/workfile', 'r') as f:
+    >>> with open('workfile', 'r') as f:
     ...     read_data = f.read()
     >>> f.closed

python/trunk/Doc/tutorial/interactive.rst

-              r2
+              r391
+   #
    # Store the file in ~/.pystartup, and set an environment variable to point
+   # to it:  "export PYTHONSTARTUP=/home/user/.pystartup" in bash.
+   #
+   # Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
+   # full path to your home directory.
+   # to it:  "export PYTHONSTARTUP=~/.pystartup" in bash.
    import atexit
 …
 One alternative enhanced interactive interpreter that has been around for quite
 some time is `IPython`_, which features tab completion, object exploration and
+some time is IPython_, which features tab completion, object exploration and
 advanced history management.  It can also be thoroughly customized and embedded
 into other applications.  Another similar enhanced interactive environment is
 `bpython`_.
+bpython_.
 …
 .. [#] Python will execute the contents of a file identified by the
    :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
+   interpreter.
+   interpreter.  To customize Python even for non-interactive mode, see
+   :ref:`tut-customize`.

python/trunk/Doc/tutorial/interpreter.rst

-              r2
+              r391
 On Windows machines, the Python installation is usually placed in
 :file:`C:\\Python26`, though you can change this when you're running the
+:file:`C:\\Python27`, though you can change this when you're running the
 installer.  To add this directory to your path,  you can type the following
 command into the command prompt in a DOS box::
    set path=%path%;C:\python26
+   set path=%path%;C:\python27
 Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
 …
 if you had spelled out its full name on the command line.
-Note that there is a difference between ``python file`` and ``python <file``.
-In the latter case, input requests from the program, such as calls to
-:func:`input` and :func:`raw_input`, are satisfied from *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 :option:`-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.)
+before the script.
 …
 When known to the interpreter, the script name and additional arguments
+thereafter are passed to the script in the variable ``sys.argv``, which is a
+list of strings.  Its length is at least one; when no script and no arguments
+thereafter are turned into a list of strings and assigned to the ``argv``
+variable in the ``sys`` module.  You can access this list by executing ``import
+sys``.  The length of the list is at least one; when no script and no arguments
 are given, ``sys.argv[0]`` is an empty string.  When the script name is given as
 ``'-'`` (meaning  standard input), ``sys.argv[0]`` is set to ``'-'``.  When
 …
    python
    Python 2.6 (#1, Feb 28 2007, 00:02:06)
+   Python 2.7 (#1, Feb 28 2010, 00:02:06)
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
 …
+.. _tut-source-encoding:
 Source Code Encoding
 --------------------
 …
 For example, to write Unicode literals including the Euro currency symbol, the
 ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value
 .  This script will print the value 8364 (the Unicode codepoint corresponding
 to the Euro symbol) and then exit::
+.  This script, when saved in the ISO-8859-15 encoding, will print the value
+(the Unicode codepoint corresponding to the Euro symbol) and then exit::
    # -*- coding: iso-8859-15 -*-
 …
+.. _tut-customize:
+The Customization Modules
+-------------------------
+Python provides two hooks to let you customize it: :mod:`sitecustomize` and
+:mod:`usercustomize`.  To see how it works, you need first to find the location
+of your user site-packages directory.  Start Python and run this code:
+   >>> import site
+   >>> site.getusersitepackages()
+   '/home/user/.local/lib/python2.7/site-packages'
+Now you can create a file named :file:`usercustomize.py` in that directory and
+put anything you want in it.  It will affect every invocation of Python, unless
+it is started with the :option:`-s` option to disable the automatic import.
+:mod:`sitecustomize` works in the same way, but is typically created by an
+administrator of the computer in the global site-packages directory, and is
+imported before :mod:`usercustomize`.  See the documentation of the :mod:`site`
+module for more details.
 .. rubric:: Footnotes
 .. [#] A problem with the GNU Readline package may prevent this.

python/trunk/Doc/tutorial/introduction.rst

-              r2
+              r391
 error will occur::
+   >>> # try to access an undefined variable
+   ... n
+   >>> n  # try to access an undefined variable
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
 …
    '"Isn\'t," she said.'
+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 produces a more
+readable output for such input strings.
 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
 …
    print hello
 Note that newlines still need to be embedded in the string using ``\n``; the
+Note that newlines still need to be embedded in the string using ``\n`` -- the
 newline following the trailing backslash is discarded.  This example would print
 the following:
 …
    This is a rather long string containing\n\
    several lines of text much as you would do in C.
-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 ``+`` operator, and
 …
    >>> 3*a[:3] + ['Boo!']
    ['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boo!']
+All slice operations return a new list containing the requested elements.  This
+means that the following slice returns a shallow copy of the list *a*::
+   >>> a[:]
+   ['spam', 'eggs', 100, 1234]
 Unlike strings, which are *immutable*, it is possible to change individual
 …
 * The *body* of the loop is *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.
+  statements.  At the interactive prompt, 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; all decent 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.
 * The :keyword:`print` statement writes the value of the expression(s) it is

python/trunk/Doc/tutorial/modules.rst

-              r2
+              r391
 A module can contain executable statements as well as function definitions.
 These statements are intended to initialize the module. They are executed only
+the *first* time the module is imported somewhere. [#]_
+the *first* time the module name is encountered in an import statement. [#]_
+(They are also run if the file is executed as a script.)
 Each module has its own private symbol table, which is used as the global symbol
 …
 .. index:: triple: module; search; path
+When a module named :mod:`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
+``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:`tut-standardmodules` for more information.
+When a module named :mod:`spam` is imported, the interpreter first searches for
+a built-in module with that name. If not found, it then searches for a file
+named :file:`spam.py` in a list of directories given by the variable
+:data:`sys.path`.  :data:`sys.path` is initialized from these locations:
+* the directory containing the input script (or the current directory).
+* :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
+  shell variable :envvar:`PATH`).
+* the installation-dependent default.
+After initialization, Python programs can modify :data:`sys.path`.  The
+directory containing the script being run is placed at the beginning of the
+search path, ahead of the standard library path. This means that scripts in that
+directory will be loaded instead of modules of the same name in the library
+directory. This is an error unless the replacement is intended.  See section
+:ref:`tut-standardmodules` for more information.
 …
 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
 depends on the underlying platform For example, the :mod:`winreg` module is only
+depends on the underlying platform.  For example, the :mod:`winreg` module is only
 provided on Windows systems. One particular module deserves some attention:
 :mod:`sys`, which is built into every Python interpreter.  The variables
 …
    >>> dir(fibo)
    ['__name__', 'fib', 'fib2']
+   >>> dir(sys)
+   ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',
+    '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',
+    'builtin_module_names', 'byteorder', 'callstats', 'copyright',
+    'displayhook', 'exc_clear', 'exc_info', 'exc_type', 'excepthook',
+    'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',
+    'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',
+    'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',
+    'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',
+    'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',
+   >>> dir(sys)  # doctest: +NORMALIZE_WHITESPACE
+   ['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__',
+    '__stderr__', '__stdin__', '__stdout__', '_clear_type_cache',
+    '_current_frames', '_getframe', '_mercurial', 'api_version', 'argv',
+    'builtin_module_names', 'byteorder', 'call_tracing', 'callstats',
+    'copyright', 'displayhook', 'dont_write_bytecode', 'exc_clear', 'exc_info',
+    'exc_traceback', 'exc_type', 'exc_value', 'excepthook', 'exec_prefix',
+    'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
+    'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
+    'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
+    'getrefcount', 'getsizeof', 'gettotalrefcount', 'gettrace', 'hexversion',
+    'long_info', 'maxint', 'maxsize', 'maxunicode', 'meta_path', 'modules',
+    'path', 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
+    'py3kwarning', 'setcheckinterval', 'setdlopenflags', 'setprofile',
+    'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', 'subversion',
     'version', 'version_info', 'warnoptions']
 …
    >>> fib = fibo.fib
    >>> dir()
    ['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']
+   ['__builtins__', '__name__', '__package__', 'a', 'fib', 'fibo', 'sys']
 Note that it lists all types of names: variables, modules, functions, etc.
 …
    >>> import __builtin__
+   >>> dir(__builtin__)
+   ['ArithmeticError', 'AssertionError', 'AttributeError', 'DeprecationWarning',
+    'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
+    'FloatingPointError', 'FutureWarning', 'IOError', 'ImportError',
+   >>> dir(__builtin__)  # doctest: +NORMALIZE_WHITESPACE
+   ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
+    'BufferError', 'BytesWarning', 'DeprecationWarning', 'EOFError',
+    'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FloatingPointError',
+    'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning',
     'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
     'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
 …
     'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
     'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
     'UserWarning', 'ValueError', 'Warning', 'WindowsError',
+    'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning',
     'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
+    '__name__', 'abs', 'apply', 'basestring', 'bool', 'buffer',
+    'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile',
+    'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
+    'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
+    'frozenset', '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', 'reversed', 'round', 'set',
+    'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
+    '__name__', '__package__', 'abs', 'all', 'any', 'apply', 'basestring',
+    'bin', 'bool', 'buffer', 'bytearray', 'bytes', 'callable', 'chr',
+    'classmethod', 'cmp', 'coerce', 'compile', 'complex', 'copyright',
+    'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval',
+    'execfile', 'exit', 'file', 'filter', 'float', 'format', 'frozenset',
+    'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input',
+    'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len', 'license',
+    'list', 'locals', 'long', 'map', 'max', 'memoryview', 'min', 'next',
+    'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit',
+    'range', 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round',
+    'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
     'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
 …
 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)::
+your package (expressed in terms of a hierarchical filesystem):
+.. code-block:: text
    sound/                          Top-level package
 …
 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
+example, the file :file:`sound/effects/__init__.py` could contain the following
 code::
 …
 .. [#] In fact function definitions are also 'statements' that are 'executed'; the
    execution of a module-level function enters the function name in the module's
    global symbol table.
+   execution of a module-level function definition enters the function name in
+   the module's global symbol table.

python/trunk/Doc/tutorial/stdlib.rst

-              r2
+              r391
    >>> import os
-   >>> os.system('time 0:02')
    >>> os.getcwd()      # Return the current working directory
    'C:\\Python26'
+   >>> os.chdir('/server/accesslogs')
+   >>> os.chdir('/server/accesslogs')   # Change current working directory
+   >>> os.system('mkdir today')   # Run the command mkdir in the system shell
 Be sure to use the ``import os`` style instead of ``from os import *``.  This
 …
 The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
 :func:`getopt` function.  More powerful and flexible command line processing is
 provided by the :mod:`optparse` module.
+provided by the :mod:`argparse` module.
 …
 There are a number of modules for accessing the internet and processing internet
 protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls
+protocols. Two of the simplest are :mod:`urllib2` for retrieving data from URLs
 and :mod:`smtplib` for sending mail::
 …
            self.assertEqual(average([20, 30, 70]), 40.0)
            self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
+           self.assertRaises(ZeroDivisionError, average, [])
+           self.assertRaises(TypeError, average, 20, 30, 70)
+           with self.assertRaises(ZeroDivisionError):
+               average([])
+           with self.assertRaises(TypeError):
+               average(20, 30, 70)
    unittest.main() # Calling from the command line invokes all tests

python/trunk/Doc/tutorial/stdlib2.rst

-              r2
+              r391
 ==========
 The :mod:`string` module includes a versatile :class:`Template` class with a
+simplified syntax suitable for editing by end-users.  This allows users to
 customize their applications without having to alter the application.
+The :mod:`string` module includes a versatile :class:`~string.Template` class
+with a simplified syntax suitable for editing by end-users.  This allows users
+to customize their applications without having to alter the application.
 The format uses placeholder names formed by ``$`` with valid Python identifiers
 …
    'Nottinghamfolk send $10 to the ditch fund.'
 The :meth:`substitute` method raises a :exc:`KeyError` when a placeholder is not
+supplied in a dictionary or a keyword argument. For mail-merge style
 applications, user supplied data may be incomplete and the
 :meth:`safe_substitute` method may be more appropriate --- it will leave
 placeholders unchanged if data is missing::
+The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
+placeholder is not supplied in a dictionary or a keyword argument.  For
+mail-merge style applications, user supplied data may be incomplete and the
+:meth:`~string.Template.safe_substitute` method may be more appropriate ---
+it will leave placeholders unchanged if data is missing::
    >>> t = Template('Return the $item to $owner.')
 …
    >>> t.substitute(d)
    Traceback (most recent call last):
      . . .
+     ...
    KeyError: 'owner'
    >>> t.safe_substitute(d)
 …
 =======================================
+The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for
+working with variable length binary record formats.  The following example shows
+The :mod:`struct` module provides :func:`~struct.pack` and
+:func:`~struct.unpack` functions for working with variable length binary
+record formats.  The following example shows
 how to loop through header information in a ZIP file without using the
 :mod:`zipfile` module.  Pack codes ``"H"`` and ``"I"`` represent two and four
 …
    logging.critical('Critical error -- shutting down')
+This produces the following output::
+This produces the following output:
+.. code-block:: none
    WARNING:root:Warning:config file server.conf not found
 …
 is sent to standard error.  Other output options include routing messages
 through email, datagrams, sockets, or to an HTTP Server.  New filters can select
+different routing based on message priority: :const:`DEBUG`, :const:`INFO`,
+:const:`WARNING`, :const:`ERROR`, and :const:`CRITICAL`.
+different routing based on message priority: :const:`~logging.DEBUG`,
+:const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
+and :const:`~logging.CRITICAL`.
 The logging system can be configured directly from Python or can be loaded from
 …
    >>> class A:
    ...     def __init__(self, value):
    ...             self.value = value
+   ...         self.value = value
    ...     def __repr__(self):
    ...             return str(self.value)
+   ...         return str(self.value)
    ...
    >>> a = A(10)                   # create a reference
 …
 performance trade-offs.
 The :mod:`array` module provides an :class:`array()` object that is like a list
+that stores only homogeneous data and stores it more compactly.  The following
+example shows an array of numbers stored as two byte unsigned binary numbers
+(typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of
 Python int objects::
+The :mod:`array` module provides an :class:`~array.array()` object that is like
+a list that stores only homogeneous data and stores it more compactly.  The
+following example shows an array of numbers stored as two byte unsigned binary
+numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
+lists of Python int objects::
    >>> from array import array
 …
    array('H', [10, 700])
 The :mod:`collections` module provides a :class:`deque()` object that is like a
+list with faster appends and pops from the left side but slower lookups in the
+middle. These objects are well suited for implementing queues and breadth first
 tree searches::
+The :mod:`collections` module provides a :class:`~collections.deque()` object
+that is like a list with faster appends and pops from the left side but slower
+lookups in the middle. These objects are well suited for implementing queues
+and breadth first tree searches::
    >>> from collections import deque
 …
    >>> print "Handling", d.popleft()
    Handling task1
+::
    unsearched = deque([starting_node])
 …
 =================================
 The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal
 floating point arithmetic.  Compared to the built-in :class:`float`
+The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
+decimal floating point arithmetic.  Compared to the built-in :class:`float`
 implementation of binary floating point, the class is especially helpful for
 …
    >>> from decimal import *
+   >>> Decimal('0.70') * Decimal('1.05')
+   >>> x = Decimal('0.70') * Decimal('1.05')
+   >>> x
    Decimal('0.7350')
+   >>> .70 * 1.05
+.73499999999999999
+The :class:`Decimal` result keeps a trailing zero, automatically inferring four
+place significance from multiplicands with two place significance.  Decimal
+reproduces mathematics as done by hand and avoids issues that can arise when
+binary floating point cannot exactly represent decimal quantities.
+Exact representation enables the :class:`Decimal` class to perform modulo
+calculations and equality tests that are unsuitable for binary floating point::
+   >>> x.quantize(Decimal('0.01'))  # round to nearest cent
+   Decimal('0.74')
+   >>> round(.70 * 1.05, 2)         # same calculation with floats
+.73
+The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
+inferring four place significance from multiplicands with two place
+significance.  Decimal reproduces mathematics as done by hand and avoids
+issues that can arise when binary floating point cannot exactly represent
+decimal quantities.
+Exact representation enables the :class:`~decimal.Decimal` class to perform
+modulo calculations and equality tests that are unsuitable for binary floating
+point::
    >>> Decimal('1.00') % Decimal('.10')

python/trunk/Doc/tutorial/whatnow.rst

-              r2
+              r391
 around 120 postings a day (with peaks up to several hundred), asking (and
 answering) questions, suggesting new features, and announcing new modules.
+Before posting, be sure to check the list of `Frequently Asked Questions
+<http://www.python.org/doc/faq/>`_ (also called the FAQ), or look for it in the
+:file:`Misc/` directory of the Python source distribution.  Mailing list
+Before posting, be sure to check the list of :ref:`Frequently Asked Questions
+<faq-index>` (also called the FAQ).  Mailing list
 archives are available at http://mail.python.org/pipermail/. The FAQ answers
 many of the questions that come up again and again, and may already contain the

Context Navigation

Legend:

python/trunk

python/trunk/Doc/tutorial/classes.rst

python/trunk/Doc/tutorial/controlflow.rst

python/trunk/Doc/tutorial/datastructures.rst

python/trunk/Doc/tutorial/errors.rst

python/trunk/Doc/tutorial/floatingpoint.rst

python/trunk/Doc/tutorial/index.rst

python/trunk/Doc/tutorial/inputoutput.rst

python/trunk/Doc/tutorial/interactive.rst

python/trunk/Doc/tutorial/interpreter.rst

python/trunk/Doc/tutorial/introduction.rst

python/trunk/Doc/tutorial/modules.rst

python/trunk/Doc/tutorial/stdlib.rst

python/trunk/Doc/tutorial/stdlib2.rst

python/trunk/Doc/tutorial/whatnow.rst

Download in other formats:

/python/vendor/Python-2.7.6	merged	eligible
/python/vendor/current	merged	eligible