Python Functions

A function is a named block of code that does one job. Built-ins such as print() and input() already give you useful jobs to call; def lets you create your own. A good name turns several lines of work into a call that says what you want done.

Write the header and body

def greet():
    print("Hello!")
    print("Welcome to Python.")

greet()
greet()

The header starts with def, then the name, parentheses and a colon. The indented lines form the body. Use four spaces for each indentation level. The unindented greet() lines are outside the function, so they are calls in the main program.

When Python reaches the definition, it creates the function and gives it the name greet. It does not print either message yet. The first call starts at the first body line and prints "Hello!" followed by "Welcome to Python." The second call starts the body again and prints the same two lines. There are four output lines in all.

A name and a call are different

The parentheses in greet() make it a call, even though this function needs no inputs. A line containing only greet refers to the function and runs nothing. print(greet) displays a description of the function object, including a memory address; it does not run the greeting.

Python must have executed a definition before a call uses its name. If a file starts with greet() and defines greet afterward, the first line raises NameError: name 'greet' is not defined. Put the definition above the top-level call.

Choose names that explain the job

Use lowercase words joined by underscores, such as print_receipt or convert_to_miles. Names may contain letters, digits and underscores, but cannot start with a digit or be a reserved word such as return. Names are case-sensitive: greet and Greet are different names.

Keep built-in names available. After input = "yes", the name input refers to text, so input("Name? ") raises TypeError: 'str' object is not callable. Naming the variable answer keeps the built-in accessible.

Repair the structure first

A missing header colon produces SyntaxError: expected ':'. An empty body or a body with no indentation produces an IndentationError. A planned function still needs a statement; pass is a placeholder that does nothing:

def print_receipt():
    pass

print_receipt()

This program runs without output. The call reaches pass and then the end of the body. Replace the placeholder with the real job when you are ready to implement it. If a line was meant to belong to the body but runs at the wrong time, check its indentation before changing the call.

A program with functions does not run every body in the order it appears on the page. A call changes the flow of execution: Python enters the called function, finishes its work, and resumes the caller just after that call.

Follow a call into another call

def line():
    print("----------")

def banner():
    line()
    print("  REPORT")
    line()

print("Start")
banner()
print("End")

First, Python defines line and banner. Neither body runs. The next statement prints "Start". The call to banner() enters its body, whose first statement calls line().

Python now enters line, prints "----------", and reaches its end. It returns to the next statement in banner, which prints " REPORT". The second line() call prints another dashed line. Finally, banner ends, so the main program resumes and prints "End".

The output is:

Start
----------
  REPORT
----------
End

Keep track of unfinished calls

While line runs, banner is waiting for it to finish. The main program is also waiting for banner. Python records these unfinished calls in the call stack. The innermost active call finishes first, and each caller resumes at its own next statement.

For a paper trace, number the program's lines. Record a body line only when execution reaches it through a call. At every call, mark where to resume. Write output when its print runs, keeping spaces and line breaks. This separates the path through the code from the output it produces.

Define helpers before they are needed

The helper's definition may appear below the caller's definition:

def show_report():
    draw_line()
    print("Ready")

def draw_line():
    print("====")

show_report()

This works because both definitions have run before the final call enters show_report. Python looks up draw_line when the body actually calls it. Moving show_report() above def draw_line(): would make the call fail when it tries to use the missing helper.

Repeated calls start fresh

A call inside a loop enters the body on each repetition:

for i in range(3):
    line()

Using the first line definition, this prints the dashed line three times. The function begins at its first body statement for every call.

If a call fails, Python shows a traceback. Its last line gives the error type and message. The call entries above it run from the outermost unfinished call down to the line that failed. Reading the final error first, then checking the innermost line and its caller, helps you locate both the failing operation and the route that supplied its data.

A function becomes reusable across different inputs when its header names the values it needs. These names are parameters. The caller supplies arguments, which are the actual values used for a particular call.

Match values to names

def rectangle_area(width, height):
    print("Area:", width * height)

rectangle_area(4, 2.5)
rectangle_area(3, 7)

The parameters are width and height. In the first call, the arguments are 4 and 2.5. Positional arguments match from left to right: width receives 4 and height receives 2.5. The body prints "Area: 10.0". The next call gives the same parameter names new values and prints "Area: 21".

Each parameter acts as a variable inside that call. You do not need to assign width and height beforehand; the call supplies them. A function without parameters still needs empty parentheses in both its definition and its calls.

Order can change the meaning

def describe_pet(animal, name):
    print(name, "is a", animal)

describe_pet("cat", "Milo")
describe_pet("Milo", "cat")

The first call prints "Milo is a cat". The second prints "cat is a Milo". Both calls are valid Python, so no error flags the swapped meaning. Read the header's order before choosing positional arguments, especially when several parameters accept the same kind of value.

Arguments can be expressions

Python evaluates each argument expression before the body starts. With side = 6, the call rectangle_area(side, side) passes 6 twice and prints "Area: 36". The caller's variable name does not have to match either parameter name. The call rectangle_area(side + 1, 2) passes 7 and 2; it does not pass the text "side + 1".

Read an argument-count error

Every parameter without a default needs an argument. With the area function above:

The first raises TypeError: rectangle_area() missing 1 required positional argument: 'height'. The second raises TypeError: rectangle_area() takes 2 positional arguments but 3 were given. Check the named function's header, then count how the call fills its parameters.

Pass the kind of value the job needs

Python does not enforce a type simply because a parameter is named width. rectangle_area("4", 2) prints "Area: 44", because multiplying text by an integer repeats that text. Since input() returns text, convert numeric input before passing it:

width = float(input("Width: "))
rectangle_area(width, 2)

Here float() turns the entered text into a number before the area function receives it.

A keyword argument names its destination parameter in the call. This makes a call easier to read when several values could be confused. Python matches the keyword to the header's name instead of using its position.

Match by name

def describe_pet(animal, name):
    print(name, "is a", animal)

describe_pet(name="Milo", animal="cat")
describe_pet(animal="cat", name="Milo")

Both calls print "Milo is a cat". The order of keyword arguments can change because each value names the parameter it fills. The same idea makes rectangle_area(width=4, height=2.5) readable without checking which dimension came first.

A keyword is not a new variable in the calling code. In describe_pet(name="Milo", animal="cat"), name= directs "Milo" to the parameter. It does not assign "Milo" to a top-level variable called name. Write keyword arguments without spaces around =, following Python's usual style.

Combine positional and keyword arguments

describe_pet("cat", name="Milo")

The first argument fills animal by position. The keyword fills name, so every parameter receives exactly one value. Positional arguments must come first. The call describe_pet(name="Milo", "cat") is rejected with SyntaxError: positional argument follows keyword argument.

To inspect a mixed call, fill the positional slots from left to right, then match the keywords. Check that no slot is filled twice and no required slot remains empty.

Fix duplicate or unknown keywords

The duplicate raises TypeError: describe_pet() got multiple values for argument 'animal'. The misspelling raises TypeError: describe_pet() got an unexpected keyword argument 'nmae'. Compare names character by character; uppercase and lowercase letters matter too. Changing argument order does not repair a duplicate assignment to one parameter.

Recognize keywords in built-ins

print("a", "b", "c", sep="-")
print("Loading", end="...")
print("done")

The first line prints "a-b-c". sep supplies the text between the displayed values. The next two calls produce "Loading...done" on one line: end replaces the usual newline after "Loading".

Some built-ins accept named arguments too; for example, round(3.14159, ndigits=2) gives 3.14. Use the parameter names documented for the function you are calling. A descriptive word you invent is not recognized just because it seems to fit the job.

A default value lets a call omit an argument when a common choice is suitable. Write the default beside its parameter in the header. Supplying an argument overrides the default for that call.

Make a parameter optional

def greet(name, greeting="Hello"):
    print(greeting + ",", name + "!")

greet("Ana")
greet("Ana", "Welcome")
greet("Ana", greeting="Hi")

The output is "Hello, Ana!", "Welcome, Ana!" and "Hi, Ana!". name is required because it has no default. greet() therefore raises a TypeError, even though the other parameter is optional.

In these headers, required parameters come before parameters with defaults. def greet(greeting="Hello", name): is invalid. Python reports a syntax error about a parameter without a default following one with a default. Move name before greeting to keep it required.

Change one optional choice

def order_coffee(size, shots=1, milk="none"):
    print(size, "coffee,", shots, "shot(s), milk:", milk)

order_coffee("large", milk="oat")

This prints "large coffee, 1 shot(s), milk: oat". The keyword reaches milk while shots keeps 1. A positional call order_coffee("medium", 2) changes shots and leaves milk at "none". Positional matching does not skip an optional parameter to reach the next one.

Built-ins also offer defaults: ordinary print() separates values with a space and ends with a newline. round(3.7) gives the whole number 4; round(3.14159, 2) requests two decimal places and gives 3.14.

Defaults are created when the definition runs

rate = 0.05

def price_with_tax(price, tax_rate=rate):
    return price * (1 + tax_rate)

rate = 0.08
print(price_with_tax(100))
print(price_with_tax(100, rate))

The default stores the value 0.05 when def runs. Changing rate later does not change that stored default. The calls print "105.0" and "108.0": only the second explicitly supplies the new rate.

Avoid sharing a list by accident

A list holds items, and append adds an item to that same list. With a list default, calls that omit the argument all share it:

def add_item(item, basket=[]):
    basket.append(item)
    print(basket)

add_item("apple")
add_item("pear")

This prints ['apple'] and then ['apple', 'pear']. The default list was made once, not once per call. To make a fresh list for each omitted argument, use None as a signal:

def add_item(item, basket=None):
    if basket is None:
        basket = []
    basket.append(item)
    print(basket)

Now those two calls print ['apple'] and ['pear']. An explicitly supplied list is still used as given. Describe optional parameters and their defaults in the docstring so callers know which values omission selects.

A function can give the caller a result to use. The return statement ends the call and sends its value back. At the calling point, the call stands for that returned value.

Store and combine results

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

area = rectangle_area(4, 2.5)
print(area)
print(rectangle_area(3, 4) + rectangle_area(2, 5))

The first call returns 10.0, which is assigned to area; the first print displays it. In the final line, the two calls return 12 and 10. Python adds those results and prints "22". The function itself contains no print, so it can supply either a saved result or part of a larger calculation.

A returned value can also be tested in a condition or passed to another function. This separates the calculation's job from the caller's decision about how to use the answer.

Printing and returning have different jobs

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

result = double_print(5)
print(result)

The call displays "10", but that displayed number is not sent back as the result. double_print reaches the end of its body, so it returns None. The last line therefore prints "None".

double_print(5) + 1 first prints "10", then raises TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'. Replace the body with return n * 2 when the caller needs the doubled number. A function intended only to produce an effect, such as displaying a message, can appropriately return None; such functions are sometimes called void. A function with a useful returned result is sometimes called fruitful.

Stop at the first executed return

def to_fahrenheit(celsius):
    return celsius * 9 / 5 + 32
    print("Converted")

print(to_fahrenheit(20))

This prints "68.0". The print inside the body is never reached because return already ended the call. Remove that unreachable statement, or move a necessary action before the return. The conversion returns floats because / produces a float. Inputs 100 and -40 give 212.0 and -40.0.

A bare return with no expression also ends a call, returning None. Every function call has a result even when no useful value was supplied.

Make results visible in a program file

A standalone rectangle_area(3, 4) computes 12 and then discards the unused result in a file. Use print(rectangle_area(3, 4)) to display it or assign it to a variable. The interactive shell displays expression results except None, so a successful shell trial can look different from running the same line in a file.

Different inputs may need different answers. A function can have several return statements, but a call stops at the first one it executes. Follow the actual path through its branches and loops to find the result.

Order overlapping tests

def letter_grade(score):
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "F"

For 85, the first test is false and the second is true. The function returns "B" without testing the remaining conditions. For 42, all three tests are false, so the final return supplies "F". Separate if statements work because each successful branch ends the call.

The highest threshold must be checked first here. If score >= 70 came first, a score of 95 would return "C". With overlapping ranges, an early broad match can hide a later, more specific answer.

Cover the path with no matching branch

def sign(n):
    if n > 0:
        return "positive"
    elif n < 0:
        return "negative"
    return "zero"

The final line handles zero. Without it, sign(0) would reach the end and return None. Trace an input from each branch and any remaining case; testing only positive and negative inputs would miss this gap.

Return a Boolean comparison

def is_even(n):
    return n % 2 == 0

if is_even(10):
    print("Even")

The comparison already produces True or False. is_even(10) returns True, while is_even(7) returns False. Use the result directly in a condition. An extra == True does not help the test.

Finish a search before reporting no match

def smallest_divisor(n):
    for d in range(2, n):
        if n % d == 0:
            return d
    return n

For 91, candidates 2 through 6 fail, then 7 divides it evenly. Returning 7 ends both the loop and the function. For 13, the loop finds no divisor, so the final return gives 13.

A test for primality needs to allow the search to continue after a failed candidate:

def is_prime(n):
    if n < 2:
        return False
    for d in range(2, n):
        if n % d == 0:
            return False
    return True

The final True is outside the loop. Putting it in an else inside the loop would return after checking only the first candidate: 9 would wrongly be accepted because it is not divisible by 2. With the corrected function, 9 and 1 return False; 2, 7 and 97 return True. For 2, the loop has no candidates, and execution reaches the final True.

Send back two values

def share(total, people):
    return total // people, total % people

each, left = share(17, 5)
print(each, left)

The call returns one tuple, a grouped result containing 3 and 2. Assignment unpacks it into two names, so the output is "3 2". Printing the call directly would show "(3, 2)". The number of names must match the number of values being unpacked.

Combine calls from the inside out

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

def to_fahrenheit(celsius):
    return celsius * 9 / 5 + 32

print(to_fahrenheit(add(10, 15)))

add first returns 25. That becomes the argument to to_fahrenheit, which returns 77.0. Finally, print displays "77.0". Each inner call must return the value the next function needs.

Scope describes where a name can be used. Parameters and names assigned inside a function are local to that function's call. A caller and a function can use similar names without sharing the same local variables.

Keep local names inside their call

def make_greeting():
    message = "Hi"
    print(message)

make_greeting()

This prints "Hi". Adding print(message) after the call raises NameError: name 'message' is not defined: the local name is not available there. To make the value available to the caller, return it and store it:

def make_greeting():
    return "Hi"

message = make_greeting()
print(message)

The top-level message is a new caller variable receiving the returned value. The function does not make its own local names visible outside.

Each call gets fresh locals. If a body sets count = 0, adds 1 and prints it, two calls print "1" and "1". The second call does not continue with the first call's count. Different functions can also use local names such as total independently.

Follow shadowing and lookup

x = 10

def show():
    x = 5
    print(x)

show()
print(x)

The output is "5" then "10". The local x shadows the global x inside show; the assignment does not change the top-level value. A global variable belongs to the file's top-level scope. Ordinary assignments outside functions create globals.

For a function defined at the file's top level, Python looks for a name in its local names, then the file's globals, then built-ins such as print. The first match wins. Local and global names are therefore different places to check when a value seems wrong.

Reassigning a parameter leaves the caller's name alone

def add_bonus(points):
    points = points + 10
    print(points)

score = 50
add_bonus(score)
print(score)

points begins with the value 50. Its local reassignment makes it 60, so the first output is "60". The caller's score is still 50. To update that name explicitly, use a function that returns points + 10, then write score = add_bonus(score).

Changing a list is a different operation

A list can be shared through two names:

def add_guest(guests, name):
    guests.append(name)

party = ["Ana"]
add_guest(party, "Ben")
print(party)

The parameter guests and caller variable party refer to the same list. append changes that list's contents, so the output is "['Ana', 'Ben']". Assigning guests = [] inside the function would instead point only the local name at a new list; party would still refer to the original. When tracing a list argument, ask whether the line changes the shared object or only reassigns a local name.

A function can read a global name without a declaration. Assigning to a name in its body follows a different rule, and confusing these operations is a common source of UnboundLocalError.

Read a fixed setting

TAX_RATE = 0.25

def tax(amount):
    return amount * TAX_RATE

print(tax(80))

The output is "20.0". amount is local; TAX_RATE is read from the file's globals. Capital letters mark a constant by convention, signaling that the program should leave the setting fixed. Python does not enforce that convention.

Assignment makes a name local throughout the body

total = 0

def add_to_total(amount):
    total = total + amount

add_to_total(5)

The assignment makes total local throughout add_to_total. To calculate the right-hand side, Python tries to read that local name before it has a value. It does not fall back to the global total. The call raises UnboundLocalError: cannot access local variable 'total' where it is not associated with a value.

The decision is based on the whole body, not just lines already executed. A body with print(count) followed by count = 10 also treats count as local at the print line. A global count cannot supply the missing local value.

Declare a deliberate global assignment

total = 0

def add_to_total(amount):
    global total
    total = total + amount

add_to_total(5)
add_to_total(7)
print(total)

Now both the read and assignment refer to the global name, so the output is "12". Put global total before any use of total in the function. Using the name before its declaration is a syntax error.

A declaration alone does not create a value. A subsequent assignment can create a global that did not exist: a function body containing global level and then level = 1 creates the global level when called.

Show the change through inputs and a result

The same running total can be written with an explicit interface:

def add_to_total(total, amount):
    return total + amount

total = 0
total = add_to_total(total, 5)
total = add_to_total(total, 7)
print(total)

This also prints "12". Each call shows the old value being passed in, and the assignment shows where the new value goes. You can check add_to_total(10, 3) on its own without first setting up hidden global state. Several functions changing the same global make their behavior depend on the order they run.

Reading a shared list and changing its contents uses the existing reference. Replacing that global name with a different list is an assignment, so the assignment rule applies.

A caller needs to know a function's job without reading all its implementation. A docstring supplies that description. Python recognizes a string as the function's docstring when it is the first statement in the body.

Write a short description first

def to_fahrenheit(celsius):
    """Convert a temperature from degrees Celsius to degrees Fahrenheit."""
    return celsius * 9 / 5 + 32

print(to_fahrenheit.__doc__)

The output is the sentence inside the quotes. Python stores the docstring in __doc__; the triple quotes are not part of the stored sentence. help(to_fahrenheit) displays the description together with the signature to_fahrenheit(celsius). Pass the function name to help, without calling the function.

The common convention is triple double quotes, even for a one-line docstring. Start with a command such as "Return the area of a rectangle." and end with a period. Keep a short description and its closing quotes on one line. You do not need to repeat the function name and parameter list because the help display already includes them.

Add detail when callers need it

def split_bill(total, people, tip_rate=0.2):
    """Return each person's share of a bill, including the tip.

    total: the bill before the tip
    people: the number of people sharing the bill
    tip_rate: the tip as a fraction of the bill (default 0.2)
    """
    return total * (1 + tip_rate) / people

The first line states the result. A blank line separates it from details about the inputs. The default is documented as 0.2, a fraction of the bill; this prevents a caller from treating 20 as the intended value for a 20 percent tip. The closing quotes of a multi-line docstring go on their own line.

For split_bill(84, 4), the function applies the default tip and returns 25.2. A caller can learn what the three inputs mean before choosing arguments. Include units when they matter and describe effects such as printing, so a caller can predict both the result and visible behavior.

Keep documentation distinct from comments

A string placed after an assignment or another body statement is not the function's docstring. It is an unused string expression, and __doc__ is None if no first-statement docstring exists. A # comment also does not become the help description.

Write the summary while deciding the function's job. If the sentence needs several unrelated actions, reconsider whether the function should be split. When you change parameters, defaults, returned values or printed effects, update the docstring at the same time; callers rely on it as part of the interface.

Decomposition means splitting a task into smaller jobs. Each function takes responsibility for one job, with clear inputs and a clear result or effect. The main program can then read as a short sequence of named steps.

Plan the data before writing the bodies

For a program that reports an average test score and a letter grade, identify three kinds of work: read scores, calculate an average, and choose a grade. Decide what each helper receives and returns. Keep the display in main, where the results come together.

def get_score(prompt):
    return float(input(prompt))

def average(a, b, c):
    return (a + b + c) / 3

def letter_grade(score):
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "F"

def main():
    first = get_score("Test 1: ")
    second = get_score("Test 2: ")
    third = get_score("Test 3: ")
    avg = average(first, second, third)
    print("Average:", round(avg, 1), "Grade:", letter_grade(avg))

main()

With scores 78, 92 and 85, average returns 85.0. That result becomes the argument to letter_grade, which returns "B". The display is "Average: 85.0 Grade: B".

main coordinates the sequence; it does not need to know how letter_grade chooses its answer. Using a function through its job and interface, without following every body statement, is procedural abstraction. You already use print in this way.

Give the caller a clear interface

A function's interface consists of its name, parameters, returned result and documented behavior. average(a, b, c) requires three numbers and returns their average. Its caller does not have to read a prompt or capture printed text to obtain that number. You can rewrite the calculation while keeping its agreed inputs and output, and existing calls still work.

Use names such as calculate_total and print_receipt for actions, and is_even or has_discount for Boolean questions. Parameter names such as price and quantity explain what values belong in each slot. One-letter names can be suitable when their meaning is clear, as in the three inputs to average.

Turn repetition into parameters

If several parts of a program print different titles between the same lines of equals signs, make the title a parameter to print_heading(title). The repeated structure belongs in one body, while the varying text belongs in the calls. A later change to the line length then needs only one edit.

Choose function boundaries that make jobs easier to understand or reuse. Putting every statement into one long main hides the smaller jobs. Splitting every trivial expression into a helper used once can add names without improving readability. A useful test is whether a short sentence can describe each job and its inputs and outputs.

Finish the file with the actual main() call after all definitions. A program containing only definitions will create its functions and finish without running their bodies.

Building several functions before running any of them makes a failure harder to locate. Incremental development means writing a small piece, checking it, then adding the next piece. You keep a working program while narrowing the amount of new code to inspect.

Use a stub while planning

A stub has the intended header and a placeholder body. A docstring and pass keep the definition valid, but the function returns None until you implement it. A fixed return can help exercise a caller's display without claiming the real calculation works yet.

Start with a calculating helper whose result you can work out independently. Once it behaves correctly, connect it to the next helper. Leave interactive input until the calculations can be checked with direct calls.

Decide expected results before running

Using the average and letter_grade functions, scores 70, 75 and 72 have an average of about 72.33, so their expected grade is "C". Check both stages:

print(average(70, 75, 72))
print(letter_grade(average(70, 75, 72)) == "C")

The outputs are "72.33333333333333" and "True". The comparison tests the expected grade directly; looking only at a program's own output without an independent expectation can let a plausible wrong answer pass.

Test edges as well as ordinary inputs

For a threshold of 90, test 90 and 89.9. The correct grade function returns "A" and "B". If its first condition were score > 90, only the exact-boundary check would reveal that 90 incorrectly falls through.

Include a typical value, exact boundaries, nearby values and extreme inputs that the function is meant to handle. For the grade function, checking 70 and 0 exercises the lowest passing boundary and the final "F" path. A check such as print(letter_grade(85) == "B") is easy because the function takes a value and returns its result.

Read the traceback and inspect the arriving value

Suppose main calls letter_grade(input("Score: ")). Entering "85" sends a string into a comparison with a number. The final error is TypeError: '>=' not supported between instances of 'str' and 'int'. The traceback points to the comparison inside the helper, while an earlier call line points to main.

The failure happens at the comparison, but the repair belongs where the input is prepared: convert it with float() before passing it. A temporary first-line print("letter_grade got", score) helps reveal an unexpected input. If its type is unclear, inspect the caller and the conversion it uses. Remove debug prints after the bug is fixed.

Connect symptoms to likely causes

After repairing a helper, rerun the checks that exercise its affected paths and the caller that connects it to the program.