--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/tutorial/controlflow.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,652 @@
+.. _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).
+