Python Function Arguments

3Function Arguments: explained step by step

In the last lesson you passed values into a function and got a result back. This lesson looks at the part that causes most beginner bugs: how Python matches the values in a call to the names in the def line, which rules control the order of those names, and what really happens to the objects you hand over.

Parameters and arguments, one more time

A parameter is a name in the def line. An argument is the value you give that name in a call. When the call starts, Python binds each argument to a parameter, exactly like an assignment such as city = "Pune". The diagram above shows that matching for one call.

Positional and keyword arguments

You can supply an argument in two ways. A positional argument is matched by its place in the call: the first value goes to the first parameter, the second to the second. A keyword argument is matched by name, as in weight=2.5. You may mix the two, but every positional argument has to come before the first keyword argument.

def ship(city, weight, express=False):
    speed = "express" if express else "standard"
    return f"{weight} kg to {city} ({speed})"

print(ship("Pune", 2.5))
print(ship("Pune", 2.5, True))
print(ship(weight=2.5, city="Pune", express=True))
print(ship("Pune", express=True, weight=2.5))

Keyword arguments can appear in any order, and they make a call readable: express=True says far more than a bare True. Python refuses to fill the same parameter twice.

The order of parameters in a def

A def line can hold four kinds of parameters. They always appear in this order:

def name(only_pos, /, normal, with_default=1, *, only_kw, kw_default=2):
    ...

• Names before the / can only be given by position.
• Names between / and * can be given either way. A normal parameter with no default may not come after one that has a default, otherwise Python raises SyntaxError: parameter without a default follows parameter with a default.
• Names after the * can only be given by keyword. They are exempt from the default rule, so a required keyword-only parameter may follow an optional one.

You rarely need all four kinds at once. The two markers let a function author protect callers from mistakes.

Keyword-only parameters

Put a bare * in the parameter list and everything after it must be passed by name. This is the right choice for flags and options, where a bare True in a call would be impossible to read.

def send_email(to, subject, *, urgent=False):
    tag = "[URGENT] " if urgent else ""
    return f"To {to}: {tag}{subject}"

print(send_email("asha@example.com", "Lunch?"))
print(send_email("asha@example.com", "Server down", urgent=True))

try:
    send_email("asha@example.com", "Server down", True)
except TypeError as error:
    print(error)

Positional-only parameters

A / in the list makes every parameter before it positional-only. Use it when the name of the parameter is not meaningful to the caller, as with the built-in len(x). It also lets you rename the parameter later without breaking anyone's code.

def clamp(value, /, low=0, high=100):
    return max(low, min(value, high))

print(clamp(150))
print(clamp(-5, low=-10))

try:
    clamp(value=150)
except TypeError as error:
    print(error)

The mutable default trap

A default value is created once, when Python executes the def line, not on every call. For a number, string or None that makes no difference, because they cannot change. For a list or dictionary it is a trap: every call that uses the default receives the same object.

def add_task(task, tasks=[]):
    tasks.append(task)
    return tasks

print(add_task("email"))
print(add_task("report"))
print(add_task.__defaults__)

The second call returns ['email', 'report'] even though you never passed the first task in. The last line shows why: the one list lives on the function itself. The standard fix is to use None as a signal and create the list inside the body:

def add_task(task, tasks=None):
    if tasks is None:
        tasks = []
    tasks.append(task)
    return tasks

print(add_task("email"))
print(add_task("report"))
today = ["standup"]
print(add_task("review", today))

Test with is None, not if not tasks: an empty list the caller passed in is falsy, and you would silently replace it.

Arguments are shared, not copied

Python does not copy the values you pass. The parameter becomes a second name for the same object. If the function changes that object (append, item assignment), the caller sees the change. If the function assigns a new value to the parameter name, only the local name moves.

def add_bonus(scores):
    for i in range(len(scores)):
        scores[i] += 5

def raise_limit(limit):
    limit = limit + 100
    return limit

marks = [60, 70]
add_bonus(marks)
print(marks)

budget = 500
print(raise_limit(budget), budget)

Be careful with +=: on a list it extends the list in place, so names += ["Zed"] changes the caller's list, while names = names + ["Zed"] builds a new one. If a function must not touch its input, work on a copy with list(scores) or return a new list.

Returning several values

A function can only return one object, but you can return a tuple and unpack it at the call site. The parentheses are optional, so return low, high is a tuple.

def min_max(numbers):
    return min(numbers), max(numbers)

result = min_max([4, 9, 2])
print(result, type(result).__name__)
low, high = min_max([4, 9, 2])
print(low, high)

If you return more than three values, or the order is easy to forget, return a dictionary so each value has a name.

Reading the TypeError messages

Calling a function with the wrong arguments raises a TypeError that names the function and the problem. Take def area(width, height):

• area() missing 1 required positional argument: 'height' means you passed too few.
• area() takes 2 positional arguments but 3 were given means you passed too many.
• area() got an unexpected keyword argument 'depth' means the name does not exist.
• area() got multiple values for argument 'width' means one parameter was filled twice, for example area(5, width=5).

Putting a positional argument after a keyword one, as in area(width=5, 3), is caught even earlier as a SyntaxError: positional argument follows keyword argument.