Defining and Calling Functions

By the end of this lesson you can define a function with required, defaulted, and keyword arguments, call it correctly, and read someone else's definition well enough to state its contract without reading a line of the body.

A function is the smallest unit of work that can be named, tested, reused, and replaced. Until code lives inside one, there is nothing to test in isolation and nothing to describe except "the script".

This also changes how you review generated code. A well-shaped function announces its contract in its first two lines: what it needs, what it gives back, and what it is called. Most of the time you can judge whether it belongs in your project before you read the implementation, and that is the difference between reviewing a change and merely approving it.

def name(parameters): introduces a function; the indented block below is its body. Nothing in the body runs until the function is called.

Parameters are the names in the definition; arguments are the values supplied at the call. They can be passed by position, in order, or by keyword, currency="EUR", in any order. Keyword arguments at a call site are self-documenting, which matters most for the arguments a reader cannot guess: search(records, True, False) tells you nothing, and search(records, include_closed=True, verbose=False) tells you everything.

A parameter can have a default: def summary(notice_id, currency="USD"). For positional parameters like those in this lesson, required parameters must come before defaulted parameters: Python fills positional arguments left to right and has no way to skip one.

When each call should start independently, avoid mutable defaults. A default is evaluated once, when the function is defined. A default list or dictionary is then shared by every call that relies on it, so mutating it can accumulate items across calls that were supposed to be independent. The convention is def collect(items=None): followed by if items is None: items = [] inside the body.

A docstring is a string on the first line of the body, and it is the contract in prose: what the function does, what it expects, what it returns, and what it does when the input is wrong. Write it before the body when you can; a docstring you cannot write is usually a function that does two things.

def format_value(amount, currency="USD", show_cents=False):
    """Render an amount as display text.

    amount: a number. currency: a three-letter code. show_cents: include
    two decimal places when True. Returns a string; never prints.
    """
    if show_cents:
        return f"{amount:,.2f} {currency}"
    return f"{amount:,.0f} {currency}"


print(format_value(185000))
print(format_value(185000, "EUR"))
print(format_value(185000, show_cents=True))
print(format_value(amount=4820.5, currency="GBP", show_cents=True))

Read the signature alone. One required parameter, two defaulted, so the function can be called with a single argument. The docstring says it returns a string and never prints, which tells the caller they are in charge of the output.

The four calls demonstrate the calling conventions in order: positional only; two positional; positional plus a keyword that skips over currency; and everything by keyword. The third call omits currency while setting show_cents by keyword. An equivalent all-positional call is format_value(185000, "USD", True); it must supply the currency explicitly.

Predict the four printed lines.

185,000 USD
185,000 EUR
185,000.00 USD
4,820.50 GBP

Change the signature to def format_value(currency="USD", amount, show_cents=False):, moving the defaulted parameter first. Predict what happens when you run the file.

SyntaxError: parameter without a default follows parameter with a default

An assistant was asked for a function that collects notice identifiers into a list, with the list optional so callers can supply their own. It produced this and said each call starts from an empty list unless one is passed.

def collect_ids(record, seen=[]):
    seen.append(record["notice_id"])
    return seen


print(collect_ids({"notice_id": "A-1"}))
print(collect_ids({"notice_id": "A-2"}))
print(collect_ids({"notice_id": "A-3"}))

['A-1']
['A-1', 'A-2']
['A-1', 'A-2', 'A-3']

def collect_ids(record, seen=None):
    if seen is None:
        seen = []
    seen.append(record["notice_id"])
    return seen

Write one small function with two required parameters and one defaulted parameter, then call it twice, once relying on the default and once overriding it by name.

Loading this exercise…

Optional: add a fourth parameter to your function, include_agency=True, and return a shorter line when it is False. Then write one sentence on whether a boolean flag that changes the shape of the return value is a good design, or whether two separate functions would be clearer. There is no single right answer, and having a position on it is what a code review needs from you.

Sign in to track your progress on this exercise.

1. What is the difference between a parameter and an argument?
2. Why must positional parameters with defaults follow required positional parameters?
3. When calls should build independent collections, why can def f(items=[]) cause a bug?
4. What can you learn from a function's signature and docstring alone?

Sign in to track your progress on this exercise.

A function names a unit of work, its signature is its contract, keyword arguments make call sites readable, defaults should avoid shared mutable state when calls need independence, and a docstring you cannot write signals a function doing two jobs. Next: what return really does, how scope decides which names a function can see, and why pure functions are so much easier to trust.