* Functions
*** Outline
***** Functions
******* review of what's been done in solving equations tutorial
********* def
********* name
********* arguments
********* indented block
********* calling a function
******* arguments are local to a function
******* return values
******* doc strings - with example.
******* code reading exercises?
******* default arguments
******* keyword arguments
******* availability library functions
*** Script
    Welcome friends. 

    In this tutorial we shall be looking at Functions in Python. We already
    have looked at the basics of functions in the tutorial on solving
    equations. We shall first review these basics. Then we shall move on to
    other details such as doc-strings, default arguments and keyword
    arguments. 
    
    First let's start IPython by typing ipython in the terminal.

    Let's write a simple function that prints a Hello message, upon
    accepting a name. 

        def welcome(name):
	    print "Hello", name 

    You would recall that def is a keyword that indicates the function
    definition. 'welcome' is the name of the function and 'name' is
    the lone argument to the function. Note that the function is
    defined within an indented block, just like to any other block. Our
    function welcome just has one line in it's definition.  
    
    We can call our function, as follows -
        welcome("World")

    (all arguments are local to a function)

    In general functions should be accompanied by documentation on how
    to use them. Python provides a convenient way of writing this within the
    function itself, using what are called doc strings. They were mentioned in the
    tutorial on strings. Let's look at how to write them here. 

    Let us add a simple doc string to our welcome function. 

        def welcome(name):
	    """ Prints a hello message given a name, 
	        passed as argument. """
	    print "Hello", name 
    
    Notice that the doc string uses triple quotes. If the doc-string
    exceeds one line, we can use new line characters in it. 
    Also, as expected the doc-string is indented as is required
    for anything within a block. Now that we have written the
    documentation, how do we access it? IPython provides the question
    mark feature that we have seen in the previous tutorials. welcome?
    will display the docstring that we have just written.

    We shall now look at default arguments. 
    [show slide with examples of functions with default arguments]
    The split function has been used in two different ways in the
    given example - one for splitting on spaces and the other for
    splitting on commas.

    The function split is being called with no arguments and one
    argument, respectively. In the first case, white space is being
    used as a default value. Let's now edit our function, welcome, to
    use default values. (For convenience sake, we have dropped the doc-string)

        def welcome(name="World!"):
	    print "Hello", name 
    
    Now, we call the function 'welcome' without passing any arguments
    to it. 
        welcome()

    As you can see the output is "Hello World!". Here "World!" is used as a
    default argument, when no name argument is passed to 'welcome'. 

    Let's now look at the use of keyword arguments. 
    [show slide with examples of functions with keyword arguments]
    We have already looked at functions and keyword arguments in these
    examples. loc, linewidth, xy, labels are all keywords. 

    Let's now edit our function so that it displays a custom 
    greeting message as well. 

    def welcome( greet = 'Hello', name = 'World!'):
        print greet, name

    Let's now see, how we can call our updated 'welcome' function, using
    keyword arguments. We can call the function in a variety of ways.
        welcome("Hello", "James")
	welcome("Hi", name="Guido")
	welcome(name="Guido", greet="Hello")

    Keyword arguments allow us to call functions by passing arguments
    in any order and removes the need to remember the order of arguments
    in the function definition. 

    Let's now write a new function 

    def per_square(n):
        i = 1
	while ( i*i < n ):
	    i += 1
	return i*i == n, i

    What does this function do? It checks if the given number is a perfect square.
    If it is, then the function returns True along with the square root of
    the given number. If the number is not a perfect square it returns
    False and the square root of the next perfect square.

    Please observe that this function returns 2 values.
    In Python there is no restriction on the number of values returned by
    a function. Whenever a function has to return more than one value, the multiple
    values are packed into one single tuple and that single tuple is returned.

    With this we come to the end of this tutorial on functions. In this tutorial
    we have learnt about functions in a greater detail. We looked at
    how to define functions, calling them, default and keyword
    arguments. 

*** Notes