5. Defining Functions

The ability to define our own functions helps programmers in two ways. When you are writing a program if you find yourself writing the same code more than once, it is probably best to define a function with the repeated code in it. Then you can call the function as many times as needed instead of rewriting the code again and again.

It is important that we avoid writing the same code more than once in our programs. Writing code is error-prone. Programmers often make mistakes. If we write the same code more than once and make a mistake in it, we must fix that mistake every place we copied the code. When writing code that will be used commercially, mistakes might not be found until years later. When fixing code that hasn’t been looked at for a while it is extremely easy to fix the code in one place and to forget to fix it everywhere.

Writing functions also helps make our code easier to read. When we use good names for variables and functions in our programs we can read the code and understand what we have written not only as we write it, but years later when we need to look at the code we wrote again. Typically programmers work with a group of three to eight other people. It is important for others in the group to be able to read and understand the code we have written. Writing functions can lead to nice modularized code that is much easier to maintain by you and by others in a group.

When we write a function we must decide four things: By considering these questions and answering them, we can make sure that our functions make sense before writing them. It does us no good to define functions that don’t have a well-defined purpose in our program.

It is important to decide the type of value returned from a function and the types of the arguments given to a function. The words returned and given are words that give us a clue about what the function should look like and what it might do. When presented with a specification for a function look for these words to help you identify what you need to write.

The word parameter refers to the identifier used to represent the value that is passed as an argument to the function. Sometimes the parameter is called a formal parameter. When a function is called, it is passed an argument as in where 6 is the argument. When the function is applied the parameter called takes on the value of 6. If it is called as then the parameter takes on the value 5. In this way we can write the function once and it will work for any argument passed to the function. In Example 5.3 the argument is the value that t refers to, the value entered by the user when the program is run. The parameter, s, takes on the value that refers to when the function is called in the print statement. The parameter passing mechanism makes it possible for us to write a function once and use it in many different places in our program with many different values passed in.

When writing functions it is important to understand scope. Scope refers to the area in a program where a variable is defined. Normally, a variable is defined after it has been assigned a value. You cannot reference a variable until it has been assigned a value.

When we define functions there are several identifiers we write. First, the name of the function is written. Like variables, a function identifier can be used after it is defined. In Example 5.3 you will notice that the function is defined at the top of the program and the function is called on the last line of the program. A function must be defined before it is used.

However, the variables s, c, and result are not available where reverse(t) is called. This is what we want to happen and is due to something called scope. The scope of a variable refers to the area in a program where it is defined. There are several scopes available in a Python program. Mark Lutz describes the rules of scope in Python with what he calls the LEGB rule [3]. Memorizing the acronym LEGB will help you memorize the scope rules of Python.

The LEGB rule refers to Local Scope, Enclosing Scope, Global Scope, and Built-in Scope. Local scope extends for the body of a function and refers to anything indented in the function definition. Variables, including the parameter, that are defined in the body of a function are local to that function and cannot be accessed outside the function. They are local variables.

Accessing a variable in the enclosing scope can be useful in some circumstances, but is not usually done unless the variable is a constant that does not change in a program. In the program above the values variable is accessed by the reverse function on the first line of its body. This is an example of using enclosing scope. However, the next example, while it does almost the same thing, has a problem.

The code in Example 5.5 does not work because of a subtle issue in Python. A new variable, say v, is defined in Python anytime v ... is written. In Example 5.5 the first line of the reverse function is values values [s]. As soon as values ... is written, there is a new local variable called values that is defined in the scope of the reverse function. That means there are two variables called values: one defined in reverse and one defined outside of reverse. The problem occurs when the right-hand side of values values [s] is evaluated. Which values is being concatenated to [s]. Is it the local or the enclosing values. Clearly, we would like it to be the enclosing values variable. But, it is not. Local scope overrides enclosing scope and the program in Example 5.5 will complain that values does not yet have a value on the first line of the reverse function’s body.

The problem with Example 5.5 can be fixed by declaring the values variable to be global. When applied to a variable, global scope means that there should not be a local copy of a variable made, even when it appears on the left hand side of an assignment statement.

Example 5.6 demonstrates the use of the global scope. The use of the global keyword forces Python to use the variable in the enclosing scope even when it appears on the left hand side of an assignment statement.

The one gotcha with scope is that local scope trumps the enclosing scope, which trumps the global scope, which trumps the built-in scope. Hence the LEGB rule. First local scope is scanned for the existence of an identifier. If that identifier is not defined in the local scope, then the enclosing scope is consulted. Again, if the identifier is not found in enclosing scope then the global scope is consulted and finally the built-in scope. This does have some implications in our programs.

The run-time stack is a data structure that is used by Python to execute programs. Python needs this run-time stack to maintain information about the state of your program as it executes. A stack is a data structure that lets you push and pop elements. You push elements onto the top of the stack and you pop elements from the top of the stack. Think of a stack of trays. You take trays off the top of the stack in a cafeteria. You put clean trays back on the top of the stack. A stack is a first in/first out data structure. Stacks can be created to hold a variety of different types of elements. The run-time stack is a stack of activation records.

An activation record is an area of memory that holds a copy of each variable that is defined in the local scope of a function while it is executing. As we learned in Example 5.5, a variable is defined when it appears on the left-hand side of an equals sign. Formal parameters of a function are also in the local scope of the function.

In Example 5.7, each time the reverse function returns to the main code the activation record is popped. Assuming the user enters the string “hello”, snapshot 1 of Fig. 5.1 shows what the run-time stack would look like right before the result is returned from the function call.

In snapshot 2, the activation record for reverse(“hello”) had been popped from the stack but is shown grayed out in snapshot 2 to make it clear that the top activation record is a new activation record. Snapshot 2 was taken right before the return result statement was executed for the second call to reverse.

Snapshot 3 shows what the run-time stack looks like after returning from the second call to reverse. Again, the grayed out activation record is not there, but is shown to emphasize that it is popped when the function returns. Finally, snapshot 4 shows what happens when the main code exits, causing the last activation record to be popped.

Each activation record holds a copy of the local variables and parameters that were passed to the function. Local variables are those variables that appear on the left-hand side of an equals sign in the body of the function or appear as parameters to the function. Recall that variables are actually references in Python, so the references or variables point to the actual values which are not stored in the activation records.

The run-time stack is absolutely critical to the implementation of modern programming languages. Its existence makes it possible for a function to execute and return independently of where it is called. This independence between functions and the code that calls them is crucial to making functions useful in our programs.

The run-time stack is visible in most debuggers including the Wing IDE. To view the activation records on the run-time stack you have to debug your program and set a breakpoint during its execution. Figure 5.2 shows the Wing IDE running the program from Example 5.4. A breakpoint was set just before the reverse function returns: the same point at snapshot one in Fig. 5.1. In Wing you can click on the Stack Data tab to view the run-time stack. The drop-down combobox directly below the Stack Data tab contains one entry for each activation record currently on the run-time stack. In Fig. 5.2 the module activation record is selected which is Wing’s name for the Main activation record. When an activation record is selected in the Stack Data tab, its local variables are displayed below. In Fig. 5.2 the t and values variables are displayed from the Main activation record. The program is currently stopped at line 10 but the reverse function was called from line 18 so that line is highlighted since we are displaying the activation record corresponding to the code reverse was called from.

If you consider Fig. 5.1, it should help in understanding that a function that mutates a value passed to it will cause the code that called it to see that mutated data. The program presented in Example 5.7 does not mutate any of the data passed to the reverse function. In fact, since strings are immutable, it would be impossible for reverse to mutate the parameter passed to it. However, Example 5.4 mutates the values list. The result of appending to the list is seen in the code that called it. Lists are not immutable. They can be changed in place. In Example 5.4 the reference to the values list is not changed. The contents of the values list is changed. The changed contents are seen by the main code after the function returns.

As another example, consider a reverse function that doesn’t return a value. What if it just changed the list that was given to it. If the parameter to the list function was called lst, then writing lst[0] “h” will change the first element of the list lst to the string h. That’s what is meant by mutating a data. A new list is not created in this case. The existing list is modified. If a list is passed to a function and the function mutates the list, the caller of the function will see the reversed list. That’s what the append method does. It mutates the existing list as well.

Notice that the reverseInPlace function in Example 5.8 does not return anything. In addition, when reverseInPlace is called it is not set to some variable, nor is the return value printed. It is just called on a line by itself. That’s because it modifies the list passed to it as an argument.

In practice Problem 5.7 the value printed to the screen is None. None is a special value in Python. It is returned by any function that does not explicitly return a value. All functions return a value in Python. Those that don’t have a return statement in them to explicitly return a value, return None by default. Obviously, printing None wouldn’t tell us much about the reverse of [1, 2, 3, 4, 5].

A predicate is an answer to a question with respect to one or more objects. For instance, we can ask, Is x even?. If the value that x refers to is even, the answer would be Yes or True. If x refers to something that is not even then the answer would be False. In Python, if we write a function that returns True or False depending on its parameters, that function is called a Predicate function. Predicate functions are usually implemented using the Guess and Check pattern. However, applying this pattern to a function can look a little different than the pattern we learned about in Chap. 2.

In Example 5.9 the guess and check pattern is applied to the function evenlyDivides. Observing that the function returns True or False it could be rewritten to just return that value instead of using a variable at all as in Example 5.10.

Since the function in Examples 5.9 and 5.10 returns True when and False when it does not, there is one more version of this function that is even more concise in its definition. Any time you have an if statement where you see if c is true then return true else return false it can be replaced by return c. You don’t need an if statement if all you want to do is return true or false based on one condition.

While the third version of the evenlyDivides function is the most elegant, this pattern may only be applied to predicate functions where only one condition needs to be checked. If we were trying to return write a predicate function that needed to check multiple conditions, then the second or first form of evenlyDivides would be required.

Without worrying further about how evenlyDivisible works we can just assume that it will work once we get around to defining it. Of course, the program won’t run until we define evenlyDivisible. But we can decide that evenlyDivisible must print a report to the screen the way the output is specified in Example 5.12. Later we can write the evenlyDivisible function. In a top-down design, when we write the evenlyDivisible function we would look to see if we could somehow make the job simpler by calling another function to help with the implementation. The evenlyDivides function could then be defined. In this way the main code calls a function to help with its implementation. Likewise, the evenlyDivisible function calls a function to aid in its implementation. This top-down approach continues until simple functions with straightforward implementations are all that is left.

In a Bottom-Up Design we would start by defining a simple function that might be useful in solving a more complex problem. For instance, the evenlyDivides function that checks to see if one value evenly divides another, could be useful in solving the problem presented in Example 5.12. Using a bottom-up approach a programmer would then see that evenlyDivides solves a slightly simpler problem and would look for a way to apply the evenlyDivides function to the problem we are solving.

Sections 5.7 and 5.8 taught us that functions can call other functions and that sometimes this helps make a complex problem more manageable in some way. It turns out that not only can functions call other functions, they can also call themselves. This too can make a problem more manageable. If you’ve ever seen a proof by induction in Mathematics, recursive functions are somewhat like inductive proofs. In an inductive proof we are given a problem and told we know it is solvable for a smaller sized problem. Induction says that if we can use that smaller solution to arrive at a bigger solution, then we can conclude every instance of that problem has a solution. What makes an inductive proof so powerful is that we don’t have to worry about the existence of a solution to the smaller problem. It is guaranteed to exist by the nature of the proof.

Recursion in functions works the same way. We may assume that our function will work if we call our function on a smaller value. Let’s consider the computation of factorial from Mathematics. by definition. This is called the base case. is defined as . This is the recursive part of the definition of factorial.

A function is recursive if it calls itself. Recursion works in Python and other languages because of the run-time stack. To fully understand how the factorial function works, you need to examine the run-time stack to see how the program prints 120 to the screen.

Many problems can be formulated in terms of recursion. For instance, reversing a string can be formulated recursively. To reverse a string we only need to reverse a shorter string, say all but the first letter, and then tack the first letter onto the other end of the reversed string. Here is the beautiful part of recursion. We can assume that reversing a shorter string already works!!!

In most programming languages one special function is identified as the main function. The main function is where everything gets started. When a program in Java runs, the main function is executed first and the code in the main function determines what the program does. The same is true in C, C, Pascal, Fortran, and many other languages. In Python this is not required by the language. However, it is good programming practice to have a main function anyway.

One advantage to defining a main function is when you wish to write a module that others may use. When importing a module a programmer probably does not want the main function in the imported module to run since he or she is undoubtably writing their own main function. The programmer writing the module that is imported may want to write a main function to test the code they are providing in the module. Python has some special handling of imported modules that allow both the provider and the importer of a module to get the behavior they desire.

By writing a main function, all variables defined in the main function are no longer available to the whole program module. An example might help in explaining why this might be important.

While the code in Example 5.15 works, it is not desirable because if a programmer changes the main code he or she may affect the code in the drawSquare function. For instance, if the programmer renames l to length at some future time, then the drawSquare function will cease to work. In addition, if drawSquare is moved to another module at some point in the future it will cease to work. A function should be as self-contained as possible to make it independent of where it is defined and where it is used.

The problem in the code above is easy to miss at first. You could easily think the program is fine since it does what it is supposed to do. The problem is due to the fact that up to this point we have not used a main function in our programs. Python programmers sometimes write a main function and sometimes do not. However, it is safer to write a main function and most experienced Python programmers will stick to the convention of writing one.

When a program has a main function in Python, the convention is to write an if statement at the end of the program that starts everything executing. There is a special hook in Python that controls how a Python program is started. When a program is imported as a module the special variable called _ _name_ _ is set to the name of the module. When a program is NOT imported, but run as the main module of a Python program, the special variable _ _name_ _ is set to the value “_ _main_ _”. When running the code in Example 5.16 the if statement’s condition is True and therefore main is called to get the program started. However, this code implements a useful function, the drawSquare function. It might be the case that some programmer would like to use this function in their code. If this code resides a file called square.py and a programmer has a copy of this module and writes import square in their code, then when this module loads the _ _name_ _ variable will be set to the name of the module and not “_ _main_ _”. If you run this code as a program then the main function gets called. If you import this module into some other program, then the main function does not get called. When a module is written that is intended to be imported into other code, the main function often contains code to test the functions provided in the module.

In Example 5.16, if the programmer were to mistakenly write turtle.forward(l) instead of turtle.forward(length), Python would complain the first time the draw Square function was called. It would say that l is undefined. This is much more desirable since we would like to catch errors like that right away as opposed to some later time.

Up to this point we have learned that arguments passed to a function must be in the same order as the formal parameters in the function definition. For instance, in Example 5.16, to call the drawSquare function we would write drawSquare(t,l) as is done in the main function of the example.

It turns out that Python allows programmers to call functions using keyword arguments as well [5]. This is not possible in every language, but this is one of the very powerful features of Python. A formal parameter in the function definition is the name given to a value that will be passed to the function. For instance, in Example 5.16 the formal parameters to drawSquare are turtle and length. These two names are also keywords that may be used when calling drawSquare. The drawSquare function can be called by writing drawSquare(lengthl,turtlet) using the keyword style of parameter passing.

When the keyword style of parameter passing is used, some keyword values may or may not be supplied depending on what the function does. In this case, a function definition can supply a default value for a parameter.

Python functions may have a variable number of parameters passed to them. To deal with this a special form of parameter is defined in Python by writing an asterisk in front of it. Writing *args as a formal parameter defines args as a list (see [5]). Every argument that is passed starting at args position will be passed in a list that args will refer to.

Using keyword/value pairs to pass values to functions is much like building a dictionary. A dictionary is a set of keys and associated values. For instance, you can assign width20 and height40 in a dictionary. Chapter 12 describes the operators and methods of dictionaries.

As an added convenience for programmers, a dictionary of keyword/value pairs may be specified as a parameter to a function [5]. The dictionary is automatically defined as the set of all keyword/value pairs passed to the function. A keyword/value dictionary parameter is defined by writing two asterisks in front of the parameter name.

These are solutions to the practice problems in this chapter. You should only consult these answers after you have tried each of them for yourself first. Practice problems are meant to help reinforce the material you have just read so make use of them.