#
4.6 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

The 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, indented by a tab stop. The first statement of the function body can optionally be a string literal; this string literal is the function's documentation string, or docstring. There are tools which use docstrings to automatically produce printed documentation, or to let the user interactively browse through code; it's good practice to include docstrings in code that you write, so try to 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 global symbol table, and then in the table of built-in names. Thus, global variables cannot be directly assigned a value within a function (unless named in a `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.4.1When 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 object at 10042ed0>
      >>> f = fib
      >>> f(100)
      1 1 2 3 5 8 13 21 34 55 89

You might object that `fib` is not a function but a procedure. In Python, like in C, procedures are just functions that don't return a value. In fact, technically speaking, procedures 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:

      >>> 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 `return` statement returns with a value from a function. `return` without an expression argument is used to return from the middle of a procedure (falling off the end also returns from a procedure), in which case the `None` value is returned.

- 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 `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.

#### Footnotes

... value.4.1
  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 (e.g., items inserted into a list).