MCL/sf/adapt/qemu: comparison symbian-qemu-0.9.1-12/python-2.6.1/Doc/tutorial/controlflow.rst

equal deleted inserted replaced

-:ffa851df0825
+:2fb8b9db1c86
+.. _tut-morecontrol:
+***********************
+More Control Flow Tools
+***********************
+Besides the :keyword:`while` statement just introduced, Python knows the usual
+control flow statements known from other languages, with some twists.
+.. _tut-if:
+:keyword:`if` Statements
+========================
+Perhaps the most well-known statement type is the :keyword:`if` statement.  For
+example::
+>>> x = int(raw_input("Please enter an integer: "))
+Please enter an integer: 42
+>>> if x < 0:
+...      x = 0
+...      print 'Negative changed to zero'
+... elif x == 0:
+...      print 'Zero'
+... elif x == 1:
+...      print 'Single'
+... else:
+...      print 'More'
+...
+More
+There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
+optional.  The keyword ':keyword:`elif`' is short for 'else if', and is useful
+to avoid excessive indentation.  An  :keyword:`if` ... :keyword:`elif` ...
+:keyword:`elif` ... sequence is a substitute for the ``switch`` or
+``case`` statements found in other languages.
+.. _tut-for:
+:keyword:`for` Statements
+=========================
+.. index::
+statement: for
+statement: for
+The :keyword:`for` statement in Python differs a bit from what you may be used
+to in C or Pascal.  Rather than always iterating over an arithmetic progression
+of numbers (like in Pascal), or giving the user the ability to define both the
+iteration step and halting condition (as C), Python's :keyword:`for` statement
+iterates over the items of any sequence (a list or a string), in the order that
+they appear in the sequence.  For example (no pun intended):
+.. One suggestion was to give a real C example here, but that may only serve to
+confuse non-C programmers.
+::
+>>> # Measure some strings:
+... a = ['cat', 'window', 'defenestrate']
+>>> for x in a:
+...     print x, len(x)
+...
+cat 3
+window 6
+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
+['defenestrate', 'cat', 'window', 'defenestrate']
+.. _tut-range:
+The :func:`range` Function
+==========================
+If you do need to iterate over a sequence of numbers, the built-in function
+:func:`range` comes in handy.  It generates lists containing arithmetic
+progressions::
+>>> range(10)
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+The given end point is never part of the generated list; ``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')::
+>>> range(5, 10)
+[5, 6, 7, 8, 9]
+>>> range(0, 10, 3)
+[0, 3, 6, 9]
+>>> range(-10, -100, -30)
+[-10, -40, -70]
+To iterate over the indices of a sequence, combine :func:`range` and :func:`len`
+as follows::
+>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
+>>> for i in range(len(a)):
+...     print i, a[i]
+...
+0 Mary
+1 had
+2 a
+3 little
+4 lamb
+.. _tut-break:
+:keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops
+=========================================================================================
+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
+terminates through exhaustion of the list (with :keyword:`for`) or when the
+condition becomes false (with :keyword:`while`), but not when the loop is
+terminated by a :keyword:`break` statement.  This is exemplified by the
+following loop, which searches for prime numbers::
+>>> for n in range(2, 10):
+...     for x in range(2, n):
+...         if n % x == 0:
+...             print n, 'equals', x, '*', n/x
+...             break
+...     else:
+...         # loop fell through without finding a factor
+...         print n, 'is a prime number'
+...
+2 is a prime number
+3 is a prime number
+4 equals 2 * 2
+5 is a prime number
+6 equals 2 * 3
+7 is a prime number
+8 equals 2 * 4
+9 equals 3 * 3
+.. _tut-pass:
+:keyword:`pass` Statements
+==========================
+The :keyword:`pass` statement does nothing. It can be used when a statement is
+required syntactically but the program requires no action. For example::
+>>> while True:
+...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
+...
+This is commonly used for creating minimal classes such as exceptions, or
+for ignoring unwanted exceptions::
+>>> class ParserError(Exception):
+...     pass
+...
+>>> try:
+...     import audioop
+... except ImportError:
+...     pass
+...
+Another place :keyword:`pass` can be used is as a place-holder for a function or
+conditional body when you are working on new code, allowing you to keep
+thinking at a more abstract level.  However, as :keyword:`pass` is silently
+ignored, a better choice may be to raise a :exc:`NotImplementedError`
+exception::
+>>> def initlog(*args):
+...     raise NotImplementedError   # Open logfile if not already open
+...     if not logfp:
+...         raise NotImplementedError  # Set up dummy log back-end
+...     raise NotImplementedError('Call log initialization handler')
+...
+If :keyword:`pass` were used here and you later ran tests, they may fail
+without indicating why.  Using :exc:`NotImplementedError` causes this code
+to raise an exception, telling you exactly where the incomplete code
+is.  Note the two calling styles of the exceptions above.
+The first style, with no message but with an accompanying comment,
+lets you easily leave the comment when you remove the exception,
+which ideally would be a good description for
+the block of code the exception is a placeholder for.  However, the
+third example, providing a message for the exception, will produce
+a more useful traceback.
+.. _tut-functions:
+Defining Functions
+==================
+We can create a function that writes the Fibonacci series to an arbitrary
+boundary::
+>>> def fib(n):    # write Fibonacci series up to n
+...     """Print a Fibonacci series up to n."""
+...     a, b = 0, 1
+...     while b < n:
+...         print b,
+...         a, b = b, a+b
+...
+>>> # Now call the function we just defined:
+... fib(2000)
+1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
+.. index::
+single: documentation strings
+single: docstrings
+single: strings, documentation
+The keyword :keyword:`def` introduces a function *definition*.  It must be
+followed by the function name and the parenthesized list of formal parameters.
+The statements that form the body of the function start at the next line, and
+must be indented.
+The first statement of the function body can optionally be a string literal;
+this string literal is the function's documentation string, or :dfn:`docstring`.
+(More about docstrings can be found in the section :ref:`tut-docstrings`.)
+There are tools which use docstrings to automatically produce online or printed
+documentation, or to let the user interactively browse through code; it's good
+practice to include docstrings in code that you write, so make a habit of it.
+The *execution* of a function introduces a new symbol table used for the local
+variables of the function.  More precisely, all variable assignments in a
+function store the value in the local symbol table; whereas variable references
+first look in the local symbol table, then in the local symbol tables of
+enclosing functions, then in the global symbol table, and finally in the table
+of built-in names. Thus, global variables cannot be directly assigned a value
+within a function (unless named in a :keyword:`global` statement), although they
+may be referenced.
+The actual parameters (arguments) to a function call are introduced in the local
+symbol table of the called function when it is called; thus, arguments are
+passed using *call by value* (where the *value* is always an object *reference*,
+not the value of the object). [#]_ When a function calls another function, a new
+local symbol table is created for that call.
+A function definition introduces the function name in the current symbol table.
+The value of the function name has a type that is recognized by the interpreter
+as a user-defined function.  This value can be assigned to another name which
+can then also be used as a function.  This serves as a general renaming
+mechanism::
+>>> fib
+<function fib at 10042ed0>
+>>> f = fib
+>>> f(100)
+1 1 2 3 5 8 13 21 34 55 89
+Coming from other languages, you might object that ``fib`` is not a function but
+a procedure since it doesn't return a value.  In fact, even functions without a
+:keyword:`return` statement do return a value, albeit a rather boring one.  This
+value is called ``None`` (it's a built-in name).  Writing the value ``None`` is
+normally suppressed by the interpreter if it would be the only value written.
+You can see it if you really want to using :keyword:`print`::
+>>> fib(0)
+>>> print fib(0)
+None
+It is simple to write a function that returns a list of the numbers of the
+Fibonacci series, instead of printing it::
+>>> def fib2(n): # return Fibonacci series up to n
+...     """Return a list containing the Fibonacci series up to n."""
+...     result = []
+...     a, b = 0, 1
+...     while b < n:
+...         result.append(b)    # see below
+...         a, b = b, a+b
+...     return result
+...
+>>> f100 = fib2(100)    # call it
+>>> f100                # write the result
+[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
+This example, as usual, demonstrates some new Python features:
+* The :keyword:`return` statement returns with a value from a function.
+:keyword:`return` without an expression argument returns ``None``. Falling off
+the end of a function also returns ``None``.
+* The statement ``result.append(b)`` calls a *method* of the list object
+``result``.  A method is a function that 'belongs' to an object and is named
+``obj.methodname``, where ``obj`` is some object (this may be an expression),
+and ``methodname`` is the name of a method that is defined by the object's type.
+Different types define different methods.  Methods of different types may have
+the same name without causing ambiguity.  (It is possible to define your own
+object types and methods, using *classes*, as discussed later in this tutorial.)
+The method :meth:`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
+``result = result + [b]``, but more efficient.
+.. _tut-defining:
+More on Defining Functions
+==========================
+It is also possible to define functions with a variable number of arguments.
+There are three forms, which can be combined.
+.. _tut-defaultargs:
+Default Argument Values
+-----------------------
+The most useful form is to specify a default value for one or more arguments.
+This creates a function that can be called with fewer arguments than it is
+defined to allow.  For example::
+def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
+while True:
+ok = raw_input(prompt)
+if ok in ('y', 'ye', 'yes'): return True
+if ok in ('n', 'no', 'nop', 'nope'): return False
+retries = retries - 1
+if retries < 0: raise IOError, 'refusenik user'
+print complaint
+This function can be called either like this: ``ask_ok('Do you really want to
+quit?')`` or like this: ``ask_ok('OK to overwrite the file?', 2)``.
+This example also introduces the :keyword:`in` keyword. This tests whether or
+not a sequence contains a certain value.
+The default values are evaluated at the point of function definition in the
+*defining* scope, so that ::
+i = 5
+def f(arg=i):
+print arg
+i = 6
+f()
+will print ``5``.
+**Important warning:**  The default value is evaluated only once. This makes a
+difference when the default is a mutable object such as a list, dictionary, or
+instances of most classes.  For example, the following function accumulates the
+arguments passed to it on subsequent calls::
+def f(a, L=[]):
+L.append(a)
+return L
+print f(1)
+print f(2)
+print f(3)
+This will print ::
+[1]
+[1, 2]
+[1, 2, 3]
+If you don't want the default to be shared between subsequent calls, you can
+write the function like this instead::
+def f(a, L=None):
+if L is None:
+L = []
+L.append(a)
+return L
+.. _tut-keywordargs:
+Keyword Arguments
+-----------------
+Functions can also be called using keyword arguments of the form ``keyword =
+value``.  For instance, the following function::
+def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
+print "-- This parrot wouldn't", action,
+print "if you put", voltage, "volts through it."
+print "-- Lovely plumage, the", type
+print "-- It's", state, "!"
+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::
+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::
+>>> def function(a):
+...     pass
+...
+>>> function(0, a=0)
+Traceback (most recent call last):
+File "<stdin>", line 1, in ?
+TypeError: function() got multiple values for keyword argument 'a'
+When a final formal parameter of the form ``**name`` is present, it receives a
+dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
+those corresponding to a formal parameter.  This may be combined with a formal
+parameter of the form ``*name`` (described in the next subsection) which
+receives a tuple containing the positional arguments beyond the formal parameter
+list.  (``*name`` must occur before ``**name``.) For example, if we define a
+function like this::
+def cheeseshop(kind, *arguments, **keywords):
+print "-- Do you have any", kind, "?"
+print "-- I'm sorry, we're all out of", kind
+for arg in arguments: print arg
+print "-" * 40
+keys = keywords.keys()
+keys.sort()
+for kw in keys: print kw, ":", keywords[kw]
+It could be called like this::
+cheeseshop("Limburger", "It's very runny, sir.",
+"It's really very, VERY runny, sir.",
+shopkeeper='Michael Palin',
+client="John Cleese",
+sketch="Cheese Shop Sketch")
+and of course it would print::
+-- Do you have any Limburger ?
+-- I'm sorry, we're all out of Limburger
+It's very runny, sir.
+It's really very, VERY runny, sir.
+----------------------------------------
+client : John Cleese
+shopkeeper : Michael Palin
+sketch : Cheese Shop Sketch
+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.
+.. _tut-arbitraryargs:
+Arbitrary Argument Lists
+------------------------
+.. index::
+statement: *
+Finally, the least frequently used option is to specify that a function can be
+called with an arbitrary number of arguments.  These arguments will be wrapped
+up in a tuple (see :ref:`tut-tuples`).  Before the variable number of arguments,
+zero or more normal arguments may occur. ::
+def write_multiple_items(file, separator, *args):
+file.write(separator.join(args))
+.. _tut-unpacking-arguments:
+Unpacking Argument Lists
+------------------------
+The reverse situation occurs when the arguments are already in a list or tuple
+but need to be unpacked for a function call requiring separate positional
+arguments.  For instance, the built-in :func:`range` function expects separate
+*start* and *stop* arguments.  If they are not available separately, write the
+function call with the  ``*``\ -operator to unpack the arguments out of a list
+or tuple::
+>>> range(3, 6)             # normal call with separate arguments
+[3, 4, 5]
+>>> args = [3, 6]
+>>> range(*args)            # call with arguments unpacked from a list
+[3, 4, 5]
+.. index::
+statement: **
+In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
+-operator::
+>>> def parrot(voltage, state='a stiff', action='voom'):
+...     print "-- This parrot wouldn't", action,
+...     print "if you put", voltage, "volts through it.",
+...     print "E's", state, "!"
+...
+>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
+>>> parrot(**d)
+-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
+.. _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::
+>>> def make_incrementor(n):
+...     return lambda x: x + n
+...
+>>> f = make_incrementor(42)
+>>> f(0)
+42
+>>> f(1)
+43
+.. _tut-docstrings:
+Documentation Strings
+---------------------
+.. index::
+single: docstrings
+single: documentation strings
+single: strings, documentation
+There are emerging conventions about the content and formatting of documentation
+strings.
+The first line should always be a short, concise summary of the object's
+purpose.  For brevity, it should not explicitly state the object's name or type,
+since these are available by other means (except if the name happens to be a
+verb describing a function's operation).  This line should begin with a capital
+letter and end with a period.
+If there are more lines in the documentation string, the second line should be
+blank, visually separating the summary from the rest of the description.  The
+following lines should be one or more paragraphs describing the object's calling
+conventions, its side effects, etc.
+The Python parser does not strip indentation from multi-line string literals in
+Python, so tools that process documentation have to strip indentation if
+desired.  This is done using the following convention. The first non-blank line
+*after* the first line of the string determines the amount of indentation for
+the entire documentation string.  (We can't use the first line since it is
+generally adjacent to the string's opening quotes so its indentation is not
+apparent in the string literal.)  Whitespace "equivalent" to this indentation is
+then stripped from the start of all lines of the string.  Lines that are
+indented less should not occur, but if they occur all their leading whitespace
+should be stripped.  Equivalence of whitespace should be tested after expansion
+of tabs (to 8 spaces, normally).
+Here is an example of a multi-line docstring::
+>>> def my_function():
+...     """Do nothing, but document it.
+...
+...     No, really, it doesn't do anything.
+...     """
+...     pass
+...
+>>> print my_function.__doc__
+Do nothing, but document it.
+No, really, it doesn't do anything.
+.. _tut-codingstyle:
+Intermezzo: Coding Style
+========================
+.. sectionauthor:: Georg Brandl <georg@python.org>
+.. index:: pair: coding; style
+Now that you are about to write longer, more complex pieces of Python, it is a
+good time to talk about *coding style*.  Most languages can be written (or more
+concise, *formatted*) in different styles; some are more readable than others.
+Making it easy for others to read your code is always a good idea, and adopting
+a nice coding style helps tremendously for that.
+For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
+it promotes a very readable and eye-pleasing coding style.  Every Python
+developer should read it at some point; here are the most important points
+extracted for you:
+* Use 4-space indentation, and no tabs.
+4 spaces are a good compromise between small indentation (allows greater
+nesting depth) and large indentation (easier to read).  Tabs introduce
+confusion, and are best left out.
+* Wrap lines so that they don't exceed 79 characters.
+This helps users with small displays and makes it possible to have several
+code files side-by-side on larger displays.
+* Use blank lines to separate functions and classes, and larger blocks of
+code inside functions.
+* When possible, put comments on a line of their own.
+* Use docstrings.
+* Use spaces around operators and after commas, but not directly inside
+bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
+* Name your classes and functions consistently; the convention is to use
+``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
+and methods.  Always use ``self`` as the name for the first method argument
+(see :ref:`tut-firstclasses` for more on classes and methods).
+* Don't use fancy encodings if your code is meant to be used in international
+environments.  Plain ASCII works best in any case.
+.. rubric:: Footnotes
+.. [#] Actually, *call by object reference* would be a better description,
+since if a mutable object is passed, the caller will see any changes the
+callee makes to it (items inserted into a list).