GNU Info

(python2.1-tut.info)Defining Functions

---

Next: More on Defining Functions Prev: pass Statements Up: More Control Flow Tools

---

Enter node , (file) or (file)node

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, 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 "docstring".

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 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_ (where the _value_ is always
an object _reference_, not the value of the object).(1) 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 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 returns `None'.  Falling
     off the end of a procedure 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 `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 ----------

(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).