Functions, part 1

Make a day09 folder for today’s files, open it in your editor, and run each script from its terminal, as on earlier days.

Since Day 1 you have been calling functions that someone else wrote: print, len, input, range, sum. Each one does a job, and you use it by name without thinking about the code inside it. Today you write your own. A function lets you give a name to a few lines of code, run them whenever you like, hand them different values each time, and get an answer back. It is the main tool for turning a long script into small pieces you can understand, reuse, and check one at a time.

A shop adds 8% sales tax to every price. Here is a script that works out the total for three prices:

# Three prices, each with 8% sales tax added
price = 4.50
total = price + price * 0.08
print(f"Total: {total:.2f}")

price = 12.00
total = price + price * 0.08
print(f"Total: {total:.2f}")

price = 7.25
total = price + price * 0.08
print(f"Total: {total:.2f}")

Total: 4.86
Total: 12.96
Total: 7.83

It works, but look at how it is built. The same two lines, the tax formula and the print, appear three times with only the price changed. That causes three problems:

• Changing it is risky. If the tax rate goes up to 10%, you must find and fix 0.08 in three places. Miss one and one total is wrong, with no error message to warn you.
• It is hard to read. Nothing in the code says “add tax”. A reader has to work out what price + price * 0.08 means each time they see it.
• It is hard to check. To test the formula you have to run the whole script and inspect every line of output.

A function is a named block of code that does one job. You write the code once, give it a name, and then call it (run it by name) as many times as you need. On Day 1 you learned that the values you pass in the parentheses are arguments; a function can also hand a value back. Here is the same script with a function called with_tax:

def with_tax(price):
    return price + price * 0.08


print(f"Total: {with_tax(4.50):.2f}")
print(f"Total: {with_tax(12.00):.2f}")
print(f"Total: {with_tax(7.25):.2f}")

Total: 4.86
Total: 12.96
Total: 7.83

The output is identical. You will learn every piece of this syntax in the next three subsections; for now, read lines 1 and 2 as “here is how to work out a price with tax”, and each with_tax(...) on lines 5 to 7 as “use that recipe on this price”. The formula now lives in one place. This is what functions give you:

A good function does one thing, and its name says what that thing is. Big programs are built from many small functions, each easy to understand and check on its own.

To use your own function, you need two steps: define it (tell Python its name and what it does) and call it (ask Python to do it now).

A function definition starts with the keyword def (short for “define”):

def function_name():
    statement
    statement

• def is a keyword, followed by the function’s name, a pair of parentheses, and a colon. This first line is the header.
• The indented lines under it are the function body: the code that runs each time the function is called. Indentation groups the body, just as it groups the lines of an if or a loop (Days 1, 4, and 5).
• The name follows the same rules as a variable name (Day 2): snake_case, letters, digits, and underscores, not starting with a digit. Because a function does something, its name is usually a verb or a verb phrase: say_hello, with_tax, print_receipt.

To call the function, write its name followed by parentheses, exactly as you call print(): say_hello().

def say_hello():
    print("Hello!")
    print("Welcome to Day 9.")


print("Start")
say_hello()
say_hello()
print("End")

Start
Hello!
Welcome to Day 9.
Hello!
Welcome to Day 9.
End

Now change one thing: keep the definition but take out the calls.

def say_hello():
    print("Hello!")
    print("Welcome to Day 9.")


print("The function is defined.")

The function is defined.

Hello! never appears. A definition on its own does nothing you can see; the body runs only when something calls the function.

Notice the two blank lines after each function in these files. Python does not need them, but the official Python style guide (called PEP 8) asks for two blank lines around a top-level function so that each definition stands out from the code around it. All of today’s examples follow it.

say_hello()


def say_hello():
    print("Hello!")

Traceback (most recent call last):
  File ".../day09/call_before_def.py", line 1, in <module>
    say_hello()
    ^^^^^^^^^
NameError: name 'say_hello' is not defined

print("A")


def show():
    print("B")


print("C")
show()
print("D")
show()

A
C
B
D
B

say_hello does the same thing every time. print and len are more useful because you hand them a value to work on. Your functions can take values too.

A parameter is a name in the function’s header, inside the parentheses, that receives a value when the function is called. An argument is the value you write in the call. When you call the function, Python assigns each argument to its parameter, exactly like an assignment statement, and then runs the body. Inside the body, the parameter is an ordinary variable.

An everyday comparison: a recipe card says “add the fruit”. “fruit” is the parameter, a blank to fill in. When you cook, you decide that today the fruit is apples: “apples” is the argument.

def greet(name):
    print(f"Hi, {name}!")


greet("Ana")
greet("Ben")
student = "Chen"
greet(student)

Hi, Ana!
Hi, Ben!
Hi, Chen!

A function can have several parameters, separated by commas. The arguments are matched to the parameters by position: the first argument goes to the first parameter, the second to the second. Arguments matched this way are called positional arguments. Here the same function is called twice with the same two values in a different order:

def describe_pet(animal, name):
    print(f"{name} is a {animal}.")


describe_pet("dog", "Rex")
describe_pet("Rex", "dog")

Rex is a dog.
dog is a Rex.

In the first call, animal = "dog" and name = "Rex". In the second call, the order is swapped, so animal = "Rex" and name = "dog". Python cannot tell that this makes no sense; it only counts positions. When you call a function with several parameters, check the order in its header.

def greet(name):
    print(f"Hi, {name}!")


greet()

Traceback (most recent call last):
  File ".../day09/greet_missing.py", line 5, in <module>
    greet()
    ~~~~~^^
TypeError: greet() missing 1 required positional argument: 'name'

def show_seat(row, seat):
    print(f"Row {row}, seat {seat}")


show_seat("C", 7)
seat = 2
row = "A"
show_seat(seat, row)

Row C, seat 7
Row 2, seat A

greet prints, and that is all it can do. But len("cat") does not print anything: it gives back 3, and you decide what to do with it, such as store it, compare it, or add 1 to it. To get a result out of your own function, you need the same ability.

The return statement, return expression, ends the function and sends the value of the expression back to the place where the function was called. That value is the function’s return value. The call itself then stands for that value: wherever you write rectangle_area(3, 4), Python runs the function and replaces the call with what it returned, the way it replaces len("cat") with 3.

def rectangle_area(width, height):
    return width * height


kitchen = rectangle_area(3, 4)
hall = rectangle_area(1.5, 6)
print("Kitchen:", kitchen)
print("Hall:", hall)
print("Total:", kitchen + hall)

Kitchen: 12
Hall: 9.0
Total: 21.0

A function can contain more than one return, usually in different branches of an if. The first return that runs ends the function at once, and any lines after it in the body are skipped. That makes a chain of if statements simple to write:

def ticket_price(age):
    if age < 12:
        return 5
    if age >= 65:
        return 6
    return 10


print(ticket_price(8))
print(ticket_price(70))
print(ticket_price(30))
print("Family of three:", ticket_price(8) + ticket_price(40) + ticket_price(42))

5
6
10
Family of three: 25

For ticket_price(8), line 2 is True, so line 3 returns 5 and the function is over; lines 4 to 6 never run, which is why the second if does not need to be an elif. For 70, the first test fails, the second passes, and it returns 6. For 30, both tests fail, and line 6 returns the standard price, 10. The last line shows a call used directly inside an expression: 5 + 10 + 10 is 25. Because a function call is an expression, you can use it anywhere a value is allowed: in a calculation, an f-string, a condition, or as the argument of another call.

def total(numbers):
    result = 0
    for n in numbers:
        result += n
        return result


print(total([4, 5, 6]))

4

def total(numbers):
    result = 0
    for n in numbers:
        result += n
    return result


print(total([4, 5, 6]))

15

def add(a, b):
    return a + b


def double(n):
    return n * 2


result = double(add(2, 3))
print(result)
print(add(double(1), 4))

10
6

Printing and returning can look alike when you run a small program: in both cases a number shows up somewhere. They do completely different jobs.

• Printing shows a value to the person at the terminal. Once printed, the program cannot use it again.
• Returning hands a value to the program, at the place where the function was called. The program can store it, do math with it, or print it later.

What does a function give back if it never reaches a return? Every call gives back something. A function that ends without running a return, or that runs a bare return with no value, returns None, the Day 2 value that means “no value here”.

def show_double(n):
    print(n * 2)


def get_double(n):
    return n * 2


a = show_double(5)
b = get_double(5)
print("a is", a)
print("b is", b)

10
a is None
b is 10

The REPL makes this easy to miss. When you type an expression at the >>> prompt, the REPL shows its value, so a returned value appears on screen even though nobody called print. But the REPL shows nothing for None:

>>> def get_double(n):
...     return n * 2
...
>>> def show_double(n):
...     print(n * 2)
...
>>> get_double(5)
10
>>> show_double(5)
10
>>> answer = get_double(5)
>>> result = show_double(5)
10
>>> print(answer, result)
10 None

get_double(5) and show_double(5) both show 10, for different reasons: the first is the REPL displaying the return value, and the second is the print inside the function. The difference appears when you store the results: storing get_double(5) prints nothing, while storing show_double(5) still prints 10 and stores None. In a script there is no automatic display, so a returned value shows up only if you print it.

The rule of thumb: a function that works something out should return it, and leave printing to the code that calls it. A function whose whole job is to show something, like greet, can print, and returns None.

def show_double(n):
    print(n * 2)


total = show_double(5) + 1
print(total)

10
Traceback (most recent call last):
  File ".../day09/none_math.py", line 5, in <module>
    total = show_double(5) + 1
            ~~~~~~~~~~~~~~~^~~
TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'

def shout(word):
    print(word.upper() + "!")


print(shout("hi"))

HI!
None

Returning has another payoff: a function that returns a value can be checked. On Day 4 you ran the grade program several times, typing a new score each time and reading the result. With a function, you can write the checks once, in code, and run them all in one go.

Testing a function means calling it with inputs whose correct answers you already know, and comparing what it returns with those answers. A simple way to start is to print each result next to the answer you expect, so a mismatch stands out. Choose inputs that matter: a typical value, and the values right at each boundary (the edges where the answer changes), because that is where mistakes hide.

def is_teen(age):
    return 13 <= age <= 19


print(is_teen(12), "expected False")
print(is_teen(13), "expected True")
print(is_teen(19), "expected True")
print(is_teen(20), "expected False")

False expected False
True expected True
True expected True
False expected False

Now suppose someone writes the comparison with < instead of <=. The same tests, plus a typical age, catch the mistake immediately:

def is_teen(age):
    return 13 < age < 19


print(is_teen(12), "expected False")
print(is_teen(13), "expected True")
print(is_teen(16), "expected True")
print(is_teen(19), "expected True")
print(is_teen(20), "expected False")

False expected False
False expected True
True expected True
False expected True
False expected False

The typical age, 16, passes, so a single test with an everyday value would have missed the bug. The two boundary tests, 13 and 19, fail, and they point straight at the cause: the ends of the range are not included. Change < back to <= and run the tests again.

Testing like this only works because is_teen returns its answer. A function that printed “teen” or “not a teen” could be checked only by a person reading the output. Day 20 shows how to turn checks like these into proper automated tests.

Once you have written a function, other people (and you, a month later) need to know how to use it: what it does, what to pass in, and what comes back, without reading every line of the body. Python has a standard place for that information.

A docstring (short for documentation string) is a string written as the first statement of a function’s body. It describes what the function does. By convention it uses triple quotes (Day 3), even when it fits on one line, and it starts with a short sentence such as “Return the area of a rectangle.” Unlike a comment, Python keeps the docstring and attaches it to the function. The built-in function help() shows a function’s header and docstring:

def rectangle_area(width, height):
    """Return the area of a rectangle."""
    return width * height


help(rectangle_area)

Help on function rectangle_area in module __main__:

rectangle_area(width, height)
    Return the area of a rectangle.

A longer docstring has a one-line summary, a blank line, then more detail, such as what each parameter means. The closing """ goes on its own line:

def with_tax(price, rate):
    """Return a price with sales tax added.

    price is the price before tax, and rate is the tax rate
    as a decimal, so 0.08 means 8%.
    """
    return price + price * rate


help(with_tax)
print(f"{with_tax(20, 0.08):.2f}")

Help on function with_tax in module __main__:

with_tax(price, rate)
    Return a price with sales tax added.

    price is the price before tax, and rate is the tax rate
    as a decimal, so 0.08 means 8%.

21.60

A reader who sees only with_tax(price, rate) might pass 8 for 8%. The docstring tells them to pass 0.08. In the REPL, help() may open a full-screen view of the text; press q to go back to the >>> prompt.

def rectangle_area(width, height):
    area = width * height
    """Return the area of a rectangle."""
    return area


help(rectangle_area)

Help on function rectangle_area in module __main__:

rectangle_area(width, height)

Inside rectangle_area, the parameters width and height exist only while the function runs. What happens to a variable you create inside a function once the call is over? And what if the rest of the program already uses the same name?

The scope of a name is the part of the program where that name can be used. Parameters, and any variable assigned inside a function’s body, are local variables: they belong to that one function. Python creates them fresh at the start of each call and throws them away when the call ends. Code outside the function cannot see them, and they do not touch any variable outside with the same name.

Think of each call as getting its own scratch paper. The function does its working on that paper, hands back the answer with return, and the paper goes in the bin.

total = 100


def add_tip(bill):
    total = bill * 1.2
    return total


meal = add_tip(50)
print("meal:", meal)
print("total:", total)

meal: 60.0
total: 100

The same rule covers parameters. A parameter is a local name that starts out referring to the argument’s value. Assigning a new value to the parameter changes only the local name. But if the argument is a list, the parameter refers to the same list, and changing the list (for example with append) changes it for the caller too. This is the aliasing you saw on Day 6:

def reset(score):
    score = 0


def add_item(items, item):
    items.append(item)


points = 42
reset(points)
print("points:", points)

cart = ["milk"]
add_item(cart, "bread")
print("cart:", cart)

points: 42
cart: ['milk', 'bread']

reset assigns score = 0, which only points the local name score at a new value; points outside is still 42. add_item does not assign to items; it calls append on the list that items and cart both refer to, so the caller sees 'bread'. Assigning to a parameter never affects the caller; changing a list through a parameter does.

def average(a, b):
    total = a + b
    return total / 2


print(average(4, 6))
print(total)

5.0
Traceback (most recent call last):
  File ".../day09/local_name_error.py", line 7, in <module>
    print(total)
          ^^^^^
NameError: name 'total' is not defined

x = 5


def change(x):
    x = x * 10
    print("inside:", x)
    return x


y = change(x)
print("outside:", x, y)

inside: 50
outside: 5 50

Variables created outside every function, at the left edge of the file, are global variables: their scope is the whole file. Can a function use them?

Reading a global variable inside a function works. When Python meets a name in a function’s body that is not local, it looks for a global with that name. That suits a setting the whole program shares, such as a tax rate:

tax_rate = 0.08


def with_tax(price):
    return price + price * tax_rate


print(f"{with_tax(10):.2f}")
tax_rate = 0.10
print(f"{with_tax(10):.2f}")

10.80
11.00

Assigning to a name inside a function is different. On Day 5 you used count = count + 1 happily; inside a function, with count defined outside, it fails:

count = 0


def add_one():
    count = count + 1


add_one()
print(count)

Traceback (most recent call last):
  File ".../day09/counter_bug.py", line 8, in <module>
    add_one()
    ~~~~~~~^^
  File ".../day09/counter_bug.py", line 5, in add_one
    count = count + 1
            ^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

This traceback has two parts, because the error happened inside a call. Read it from the bottom: the error is on line 5, in add_one, and the line above says Python got there from the call on line 8.

Here is why it happens. Before a function runs, Python looks through its whole body. Any name that is assigned anywhere in the body is local for the entire function. count is assigned on line 5, so count is local everywhere in add_one, including on the right side of that same line. Python works out the right side first, looks for a local count, and finds that it has not been given a value yet. UnboundLocalError is the error for “this local variable exists but has no value yet”. (Older Python versions word it local variable 'count' referenced before assignment.)

There are two fixes. Python’s global statement tells it that a name in this function means the global variable:

count = 0


def add_one():
    global count
    count = count + 1


add_one()
add_one()
print(count)

2

global count on line 5 means the assignment on line 6 changes the global count. It works, but it makes the function harder to understand and test: calling add_one() quietly changes something outside it, and you cannot tell what from the call. The usual fix is the one this whole day has been building: pass the value in as an argument and return the new value.

def add_one(count):
    return count + 1


count = 0
count = add_one(count)
count = add_one(count)
print(count)

2

Now everything add_one uses comes in through its parameter, and everything it produces goes out through return. Lines 6 and 7 make the change visible right where it happens.

level = 1


def level_up(level):
    level = level + 1
    return level


def show_level():
    print("Level", level)


level_up(level)
show_level()
level = level_up(level)
show_level()

Level 1
Level 2

A return statement hands back one value. But some jobs have two answers: dividing minutes into hours and minutes, or finding the lowest and highest score. Day 7 gave you the tool: write several values separated by commas, and Python packs them into one tuple.

To return multiple values, write them after return separated by commas: return hours, minutes. The function still returns one value, a tuple, and the caller can unpack it into separate names, as on Day 7.

def to_hours(total_minutes):
    hours = total_minutes // 60
    minutes = total_minutes % 60
    return hours, minutes


h, m = to_hours(135)
print(f"{h} h {m} min")

result = to_hours(135)
print(result)

2 h 15 min
(2, 15)

The values can come straight from other function calls. Here min and max from Day 6 work out the two answers:

def score_range(scores):
    return min(scores), max(scores)


low, high = score_range([72, 95, 64, 88])
print("Lowest:", low)
print("Highest:", high)
print("Spread:", high - low)

Lowest: 64
Highest: 95
Spread: 31

Unpacking matches by position, exactly like arguments and parameters: the first name gets the first value returned. Name your variables in the same order as the return, and say the order in the docstring when you write one.

def to_hours(total_minutes):
    return total_minutes // 60, total_minutes % 60


h, m, s = to_hours(135)

Traceback (most recent call last):
  File ".../day09/unpack_wrong.py", line 5, in <module>
    h, m, s = to_hours(135)
    ^^^^^^^
ValueError: not enough values to unpack (expected 3, got 2)

def divide(total, people):
    each = total // people
    left = total % people
    return each, left


left, each = divide(17, 5)
print("each:", each)
print("left:", left)

each: 2
left: 3

A teacher keeps each student’s quiz scores in a dictionary (Day 8) and wants a report: each student’s average and letter grade. Instead of one long loop, the program is broken into small functions that each do one thing:

def average(scores):
    """Return the average of a list of scores."""
    return sum(scores) / len(scores)


def letter_grade(score):
    """Return the letter grade for a score from 0 to 100."""
    if score >= 90:
        return "A"
    elif score >= 80:
        return "B"
    elif score >= 70:
        return "C"
    elif score >= 60:
        return "D"
    return "F"


def report_line(name, scores):
    """Return one line of the report for one student."""
    avg = average(scores)
    return f"{name}: {avg:.1f} ({letter_grade(avg)})"


class_scores = {
    "Ana": [92, 88, 95],
    "Ben": [71, 64, 80],
    "Chen": [85, 90, 78],
}
for name, scores in class_scores.items():
    print(report_line(name, scores))

Ana: 91.7 (A)
Ben: 71.7 (C)
Chen: 84.3 (B)

Follow Ana through the loop at the bottom:

1. class_scores.items() gives "Ana" and [92, 88, 95], unpacked into name and scores (Day 8).
2. report_line("Ana", [92, 88, 95]) is called. Its parameters are local, so they do not clash with the loop’s name and scores, even though they share the names.
3. Inside it, average(scores) returns 275 / 3, which is 91.666…, stored in the local avg.
4. letter_grade(avg) is called inside the f-string; 91.666… passes >= 90, so it returns "A".
5. The f-string shows avg with :.1f (Day 3), so report_line returns "Ana: 91.7 (A)", and the loop prints it.

Notice what the design buys you:

• Each function is short enough to read in one glance, and its docstring says what it does.
• Only the loop at the bottom prints. The three functions return values, so each can be tested on its own: letter_grade(90) should return "A", and average([80, 90]) should return 85.0.
• letter_grade has no reason to know about dictionaries or names, so it could be reused in any program that grades a number.
• Everything a function needs comes in through its parameters; nothing depends on global variables.

• A function names a block of code that does one job. def name(parameters): defines it without running it; name(arguments) calls it, runs the body, and comes back. Functions give you reuse, readable names, and pieces you can test.
• Parameters are the names in the header; arguments are the values in the call, matched by position. A call with the wrong number of arguments is a TypeError.
• return value ends the function and hands the value back to the caller. Printing shows a value to the person; returning gives it to the program. A function with no return gives back None.
• Test a function by calling it with known answers, especially at the boundaries. A docstring on the first line of the body says what the function does, and help() shows it.
• Parameters and variables assigned in a function are local. A function can read global variables, but assigning to a name makes it local; pass values in and return results instead. return a, b returns a tuple, which the caller unpacks.

Do these in your day09 folder. Type each program yourself, run it, and only then open the answer.

def fahrenheit_to_celsius(fahrenheit):
    """Return a Fahrenheit temperature converted to Celsius."""
    return (fahrenheit - 32) * 5 / 9


fahrenheit = 72
celsius = fahrenheit_to_celsius(fahrenheit)
print(fahrenheit, "degrees Fahrenheit is", round(celsius, 1), "degrees Celsius")

# Quick checks with answers we already know
print(fahrenheit_to_celsius(212), "expected 100.0")
print(fahrenheit_to_celsius(32), "expected 0.0")

72 degrees Fahrenheit is 22.2 degrees Celsius
100.0 expected 100.0
0.0 expected 0.0

def letter_grade(score):
    """Return the letter grade for a score, or None if it is not 0 to 100."""
    if not 0 <= score <= 100:
        return None
    elif score >= 90:
        return "A"
    elif score >= 80:
        return "B"
    elif score >= 70:
        return "C"
    elif score >= 60:
        return "D"
    else:
        return "F"


score = float(input("Score: "))
grade = letter_grade(score)
if grade is None:
    print("Scores run from 0 to 100.")
else:
    print("Grade:", grade)

Score: 89.5
Grade: B

def is_prime(n):
    """Return True if n is a prime number, otherwise False."""
    if n < 2:
        return False
    for divisor in range(2, n):
        if n % divisor == 0:
            return False
    return True


primes = []
for number in range(1, 100):
    if is_prime(number):
        primes.append(number)
print(primes)
print(len(primes), "primes under 100")

[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
25 primes under 100

def count_total_average(numbers):
    """Return the count, total, and average of a list of numbers.

    The average is None when the list is empty.
    """
    count = len(numbers)
    total = sum(numbers)
    average = total / count if count > 0 else None
    return count, total, average


count, total, average = count_total_average([4, 8, 15, 16, 23, 42])
print(f"{count} numbers, total {total}, average {average}")

count, total, average = count_total_average([])
print(f"{count} numbers, total {total}, average {average}")

6 numbers, total 108, average 18.0
0 numbers, total 0, average None

def mystery(n):
    print("got", n)
    if n > 10:
        return "big"


print(mystery(15))
print(mystery(3))

got 15
big
got 3
None

def has_negative(numbers):
    for n in numbers:
        if n < 0:
            return True
        else:
            return False


print(has_negative([3, -1, 4]))

def has_negative(numbers):
    for n in numbers:
        if n < 0:
            return True
    return False


print(has_negative([3, -1, 4]))
print(has_negative([3, 1, 4]))
print(has_negative([]))

True
False
False

rate = 2


def pay(hours, rate):
    rate = rate + 1
    return hours * rate


print(pay(4, 10))
print(rate)

44
2

The official Python Tutorial covers today’s ideas in More Control Flow Tools: Defining Functions, and its section on Documentation Strings shows the docstring conventions. The parts after that, on default and keyword arguments, are tomorrow’s topic, Day 10.

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can explain why a function is better than copying the same code. Reread
• I can define a function with def and say when its body runs. Reread
• I can tell a parameter from an argument and match arguments by position. Reread
• I can use return to send a value back and use the call in an expression. Reread
• I can choose between returning and printing, and spot a function that gives back None. Reread
• I can test a function with known answers, including the boundaries. Reread
• I can write a docstring and read one with help(). Reread
• I can explain which variables are local to a function. Reread
• I can explain why assigning to a global inside a function fails, and fix it with a parameter and return. Reread
• I can return several values and unpack them in the right order. Reread