| |
| :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: ")) |
n | 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' |
n | ... |
n | ... |
| 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` ... |
n | :keyword:`elif` ... sequence is a substitute for the :keyword:`switch` or |
n | :keyword:`elif` ... sequence is a substitute for the ``switch`` or |
| :keyword:`case` statements found in other languages. |
| ``case`` statements found in other languages. |
| |
| .. % Weird spacings happen here if the wrapping of the source text |
| .. % gets changed in the wrong way. |
| |
| |
| .. _tut-for: |
| |
| :keyword:`for` Statements |
| ========================= |
| |
| .. index:: |
| |
| 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): |
| |
n | .. % One suggestion was to give a real C example here, but that may only |
n | .. One suggestion was to give a real C example here, but that may only serve to |
| .. % serve to confuse non-C programmers. |
| confuse non-C programmers. |
| |
| :: |
| |
| >>> # Measure some strings: |
| ... a = ['cat', 'window', 'defenestrate'] |
| >>> for x in a: |
| ... print x, len(x) |
n | ... |
n | ... |
| 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) |
n | ... |
n | ... |
| >>> a |
| ['defenestrate', 'cat', 'window', 'defenestrate'] |
| |
| |
| .. _tut-range: |
| |
| The :func:`range` Function |
| ========================== |
| |
| >>> range(5, 10) |
| [5, 6, 7, 8, 9] |
| >>> range(0, 10, 3) |
| [0, 3, 6, 9] |
| >>> range(-10, -100, -30) |
| [-10, -40, -70] |
| |
n | To iterate over the indices of a sequence, combine :func:`range` and :func:`len` |
n | To iterate over the indices of a sequence, you can combine :func:`range` and |
| as follows:: |
| :func:`len` as follows:: |
| |
| >>> a = ['Mary', 'had', 'a', 'little', 'lamb'] |
| >>> for i in range(len(a)): |
| ... print i, a[i] |
n | ... |
n | ... |
| 0 Mary |
| 1 had |
| 2 a |
| 3 little |
| 4 lamb |
n | |
| In most such cases, however, it is convenient to use the :func:`enumerate` |
| function, see :ref:`tut-loopidioms`. |
| |
| |
| .. _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:`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: |
n | ... pass # Busy-wait for keyboard interrupt |
n | ... pass # Busy-wait for keyboard interrupt (Ctrl+C) |
| ... |
| ... |
| |
n | This is commonly used for creating minimal classes:: |
| |
| >>> class MyEmptyClass: |
| ... 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. The :keyword:`pass` is silently ignored:: |
| |
| >>> def initlog(*args): |
| ... pass # Remember to implement this! |
| ... |
| |
| .. _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 |
n | ... |
n | ... |
| >>> # 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 |
n | must be indented. |
| |
| must be indented. The first statement of the function body can optionally be a |
| The first statement of the function body can optionally be a string literal; |
| string literal; this string literal is the function's documentation string, or |
| this string literal is the function's documentation string, or :dfn:`docstring`. |
| :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 |
n | practice to include docstrings in code that you write, so try to make a habit of |
n | practice to include docstrings in code that you write, so make a habit of it. |
| 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 |
n | first look in the local symbol table, then in the global symbol table, and then |
n | 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 |
| in the table of built-in names. Thus, global variables cannot be directly |
| of built-in names. Thus, global variables cannot be directly assigned a value |
| assigned a value within a function (unless named in a :keyword:`global` |
| within a function (unless named in a :keyword:`global` statement), although they |
| statement), although they may be referenced. |
| 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. |
| mechanism:: |
| |
| >>> fib |
| <function fib at 10042ed0> |
| >>> f = fib |
| >>> f(100) |
| 1 1 2 3 5 8 13 21 34 55 89 |
| |
n | You might object that ``fib`` is not a function but a procedure. In Python, |
n | Coming from other languages, you might object that ``fib`` is not a function but |
| like in C, procedures are just functions that don't return a value. In fact, |
| a procedure since it doesn't return a value. In fact, even functions without a |
| technically speaking, procedures do return a value, albeit a rather boring one. |
| :keyword:`return` statement do return a value, albeit a rather boring one. This |
| This value is called ``None`` (it's a built-in name). Writing the value |
| value is called ``None`` (it's a built-in name). Writing the value ``None`` is |
| ``None`` is normally suppressed by the interpreter if it would be the only value |
| normally suppressed by the interpreter if it would be the only value written. |
| written. You can see it if you really want to:: |
| You can see it if you really want to using :keyword:`print`:: |
| |
n | >>> 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 |
n | ... |
n | ... |
| >>> 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 |
n | the end of a procedure also returns ``None``. |
n | 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.) |
| 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 |
n | ... |
n | ... |
| >>> 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 |
n | dictionary (XXX reference: ../lib/typesmapping.html) containing all keyword |
n | dictionary (see :ref:`typesmapping`) containing all keyword arguments except for |
| arguments except for those corresponding to a formal parameter. This may be |
| those corresponding to a formal parameter. This may be combined with a formal |
| combined with a formal parameter of the form ``*name`` (described in the next |
| parameter of the form ``*name`` (described in the next subsection) which |
| subsection) which receives a tuple containing the positional arguments beyond |
| receives a tuple containing the positional arguments beyond the formal parameter |
| the formal parameter list. (``*name`` must occur before ``**name``.) For |
| list. (``*name`` must occur before ``**name``.) For example, if we define a |
| example, if we define a function like this:: |
| function like this:: |
| |
| def cheeseshop(kind, *arguments, **keywords): |
n | print "-- Do you have any", kind, '?' |
n | print "-- Do you have any", kind, "?" |
| print "-- I'm sorry, we're all out of", kind |
| for arg in arguments: print arg |
n | print '-'*40 |
n | print "-" * 40 |
| keys = keywords.keys() |
| keys.sort() |
n | for kw in keys: print kw, ':', keywords[kw] |
n | for kw in keys: print kw, ":", keywords[kw] |
| |
| It could be called like this:: |
| |
n | cheeseshop('Limburger', "It's very runny, sir.", |
n | cheeseshop("Limburger", "It's very runny, sir.", |
| "It's really very, VERY runny, sir.", |
n | client='John Cleese', |
| shopkeeper='Michael Palin', |
n | client="John Cleese", |
| sketch='Cheese Shop Sketch') |
| 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. |
| ---------------------------------------- |
| not done, the order in which the arguments are printed is undefined. |
| |
| |
| .. _tut-arbitraryargs: |
| |
| Arbitrary Argument Lists |
| ------------------------ |
| |
n | .. 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 |
n | up in a tuple. Before the variable number of arguments, zero or more normal |
n | up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments, |
| arguments may occur. :: |
| zero or more normal arguments may occur. :: |
| |
n | def fprintf(file, format, *args): |
n | def write_multiple_items(file, separator, *args): |
| file.write(format % 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 |
| 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] |
n | |
| .. 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, "!" |
| 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. |
n | ... |
n | ... |
| ... No, really, it doesn't do anything. |
| ... """ |
| ... pass |
n | ... |
n | ... |
| >>> print my_function.__doc__ |
| Do nothing, but document it. |
| |
| No, really, it doesn't do anything. |
| |
| |
n | .. _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 |
| |
t | .. [#] Actually, *call by object reference* would be a better description, since if a |
t | .. [#] Actually, *call by object reference* would be a better description, |
| mutable object is passed, the caller will see any changes the callee makes to it |
| since if a mutable object is passed, the caller will see any changes the |
| (items inserted into a list). |
| callee makes to it (items inserted into a list). |
| |