diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/tutorial/controlflow.rst --- /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 + + >>> 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 "", 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 +.. 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). +