Changeset 391 for python/trunk/Doc/tutorial/controlflow.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/tutorial/controlflow.rst (modified) (10 diffs)

python/trunk/Doc/tutorial/controlflow.rst

@@ -60 +60 @@
 
    >>> # 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
@@ -68 +68 @@
    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']
 
@@ -129 +129 @@
 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
@@ -156 +153 @@
    8 equals 2 * 4
    9 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
 
 
@@ -381 +405 @@
 -----------------
 
-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'):
@@ -390 +414 @@
        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):
@@ -430 +459 @@
        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::
@@ -455 +485 @@
    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:
@@ -513 +542 @@
 .. _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):
@@ -533 +561 @@
    >>> f(1)
    43
+
+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')]