Hands-on lab — Day 57: Functions: Definition, Arguments, and Return Values

#!/usr/bin/env python3
"""demo.py — drive the function library and use its return values.

Run this from the lab directory to see the library in action:

    python3 examples/demo.py

It imports the pure functions from library.py and *uses what they return* —
composing calls, unpacking a returned tuple, and passing keyword arguments —
without any function printing on its own. All the printing happens here, in
the caller, which is exactly the pure-function-plus-thin-shell shape the
lesson teaches.
"""
import sys
from pathlib import Path

# Make the sibling library.py importable no matter where this is run from.
sys.path.insert(0, str(Path(__file__).resolve().parent))

from library import (
    clamp,
    greet,
    is_palindrome,
    mean,
    normalize_whitespace,
    reverse_words,
    summarize,
    tally,
    word_count,
)


def main():
    """Call the library functions and print how their return values are used."""
    sentence = "  the  quick   brown fox  "
    clean = normalize_whitespace(sentence)
    print(f"normalize_whitespace -> {clean!r}")
    print(f"word_count           -> {word_count(clean)}")
    print(f"reverse_words        -> {reverse_words(clean)!r}")

    print(f"is_palindrome('Racecar')        -> {is_palindrome('Racecar')}")
    print(f"is_palindrome('function')       -> {is_palindrome('function')}")

    # Default vs keyword arguments.
    print(f"greet('Ada')                    -> {greet('Ada')!r}")
    print(f"greet('Grace', 'Welcome')       -> {greet('Grace', 'Welcome')!r}")
    print(f"greet('Alan', punctuation='.')  -> {greet('Alan', punctuation='.')!r}")

    # Default arguments on clamp.
    print(f"clamp(1.5)                      -> {clamp(1.5)}")
    print(f"clamp(42, high=100)             -> {clamp(42, high=100)}")

    # Unpacking a returned tuple of several results.
    readings = [7, 3, 9, 4, 6]
    count, total, low, high, average = summarize(readings)
    print(f"summarize({readings}) ->")
    print(f"    count={count} total={total} min={low} max={high} mean={average}")
    print(f"mean(readings)                  -> {mean(readings)}")

    # Purity of tally: two calls do not leak state into each other.
    print(f"tally(['a','b','a'])            -> {tally(['a', 'b', 'a'])}")
    print(f"tally(['x'])                    -> {tally(['x'])}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""library.py — a small library of well-documented, pure functions.

Every function here takes its input as arguments and hands back a *return
value*; none of them read the keyboard, print results, or change anything
outside themselves. That makes them "pure": for the same arguments they
give the same answer, and calling them has no side effects. Pure functions
are the easy ones to test, because a test just calls the function and
checks what comes back.

The module is a grab-bag of tiny text and number utilities that together
show every idea from the Day 57 lesson:

    - def syntax and a good docstring on every function
    - positional, keyword, and default arguments      (greet, clamp)
    - a return value the caller uses, and the implicit None
    - returning a tuple to hand back several results   (summarize)
    - the mutable-default-argument trap, avoided with None (tally)

Import it and call the functions; nothing runs on import, because there is
no top-level code — only definitions. See examples/demo.py for a session
that calls these functions and uses their return values.
"""


def word_count(text):
    """Return the number of whitespace-separated words in text.

    >>> word_count("the quick brown fox")
    4
    >>> word_count("   ")
    0
    """
    return len(text.split())


def normalize_whitespace(text):
    """Return text with every run of whitespace collapsed to one space and
    the ends stripped.

    >>> normalize_whitespace("  hello   world  ")
    'hello world'
    """
    return " ".join(text.split())


def reverse_words(text):
    """Return text with its words in reverse order.

    >>> reverse_words("one two three")
    'three two one'
    """
    return " ".join(reversed(text.split()))


def is_palindrome(text):
    """Return True if text reads the same forwards and backwards, ignoring
    case and any character that is not a letter or digit.

    >>> is_palindrome("A man, a plan, a canal: Panama")
    True
    >>> is_palindrome("hello")
    False
    """
    cleaned = [character.lower() for character in text if character.isalnum()]
    return cleaned == cleaned[::-1]


def celsius_to_fahrenheit(celsius):
    """Return the Fahrenheit value for a Celsius temperature.

    >>> celsius_to_fahrenheit(100)
    212.0
    >>> celsius_to_fahrenheit(0)
    32.0
    """
    return celsius * 9 / 5 + 32


def clamp(value, low=0.0, high=1.0):
    """Return value limited to the range [low, high].

    low and high are default arguments, so clamp(x) limits x to [0.0, 1.0],
    while clamp(x, -10, 10) uses your own range. Passing them by keyword —
    clamp(x, high=100) — is clearer at the call site than a bare number.

    >>> clamp(1.5)
    1.0
    >>> clamp(-3, low=-10, high=10)
    -3
    """
    if low > high:
        raise ValueError("low must not be greater than high")
    return max(low, min(value, high))


def mean(numbers):
    """Return the arithmetic mean of a sequence of numbers.

    Raises ValueError on an empty sequence, because the mean of nothing is
    undefined — a clear error is better than a hidden division by zero.

    >>> mean([2, 4, 6])
    4.0
    """
    if not numbers:
        raise ValueError("mean of an empty sequence is undefined")
    return sum(numbers) / len(numbers)


def summarize(numbers):
    """Return a tuple (count, total, minimum, maximum, mean) for numbers.

    This is the multiple-results pattern: instead of five separate function
    calls that each re-scan the data, one call hands back a tuple the caller
    can unpack:

        count, total, low, high, average = summarize(readings)

    Raises ValueError on an empty sequence.

    >>> summarize([2, 4, 6])
    (3, 12, 2, 6, 4.0)
    """
    if not numbers:
        raise ValueError("cannot summarize an empty sequence")
    count = len(numbers)
    total = sum(numbers)
    return (count, total, min(numbers), max(numbers), total / count)


def greet(name, greeting="Hello", punctuation="!"):
    """Return a greeting line for name.

    name is required (positional); greeting and punctuation have defaults.
    All three can be passed by position or by keyword, so every call below
    is valid:

        greet("Ada")                       -> 'Hello, Ada!'
        greet("Ada", "Welcome")            -> 'Welcome, Ada!'
        greet("Ada", punctuation=".")      -> 'Hello, Ada.'

    >>> greet("Ada")
    'Hello, Ada!'
    >>> greet("Grace", greeting="Welcome", punctuation=".")
    'Welcome, Grace.'
    """
    return f"{greeting}, {name}{punctuation}"


def tally(items, counts=None):
    """Return a frequency dict counting how often each item appears.

    The default for counts is None, NOT {}. A mutable default (counts={})
    would be created once when the function is defined and then SHARED
    across every call, so counts would remember items from previous calls —
    the classic mutable-default-argument bug. Using None and building a
    fresh dict inside avoids it. When a starting tally is passed in, it is
    copied rather than mutated, so this function stays pure.

    >>> tally(["a", "b", "a"])
    {'a': 2, 'b': 1}
    >>> tally(["a"], {"a": 5})
    {'a': 6}
    """
    result = dict(counts) if counts is not None else {}
    for item in items:
        result[item] = result.get(item, 0) + 1
    return result

lesson_id: D057
day: 57
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-057-functions-definition-arguments-and-return-values
  - python3 --version
run_commands:
  - python3 examples/demo.py
  - python3 -c "import sys; sys.path.insert(0, 'examples'); from library import summarize; print(summarize([7, 3, 9, 4, 6]))"
  - python3 -c "import sys; sys.path.insert(0, 'examples'); from library import greet; print(greet('Ada', punctuation='.'))"
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'find . -name __pycache__ -type d -prune -exec rm -rf {} +  # optional: remove import caches'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-13'
executed_on: 'macOS (Apple Silicon), Python 3.14.0, bash tests/run_tests.sh -> 30 checks, 0 failure(s), exit 0'

# Dependencies — Day 057 lab

**Python 3 only. No third-party packages.**

- `python3` (3.8 or newer; tested on 3.14.0). Preinstalled on most Linux
  distributions and installable on macOS; you set this up on Day 43.
- `bash` for the test runner (preinstalled on macOS and Linux).
- Only Python's built-in language features are used — `def`, arguments,
  return values, and the standard modules `sys`, `pathlib`, and `inspect`
  that ship with Python. There is deliberately no `requirements.txt`: a
  library of pure functions should run on a plain Python install with
  nothing to download first.

Check your Python is present and new enough:

```bash
python3 --version
```

If that prints `Python 3.8` or higher, you are ready. Windows users: run the
commands inside WSL, or use `python` in place of `python3` if that is how
Python is exposed on your system. The functions are pure standard-library
Python and behave identically everywhere.

# Function design worksheet

Fill this in *before* writing code for the practice assignment. Designing a
function on paper first — its name, what it takes, what it returns, and
whether it is pure — is the discipline the lesson teaches. One row per
function you plan to add to your own library.

## The library

- **What family of things does it work with (text? numbers? dates?):**
- **File name (a module of functions, one per idea):**

## Functions

| Function name | Parameters (with defaults) | Returns (type + meaning) | Pure? (no printing / no outside change) | One example call and its result |
| ------------- | -------------------------- | ------------------------ | --------------------------------------- | ------------------------------- |
|               |                            |                          |                                         |                                 |
|               |                            |                          |                                         |                                 |
|               |                            |                          |                                         |                                 |

## Arguments to practise

- **One function that uses a default argument, and why the default is a good
  choice:**
- **One function that returns a TUPLE of several results, and what a caller
  unpacks from it:**
- **If any function takes a list or dict argument, confirm its default is
  `None` (not `[]` or `{}`) and say why:**

## Docstrings

For each function, its docstring's first line should say what it *returns*.
Write that first line here for each:

1.
2.
3.

## Recorded behaviour (fill in after you build it)

- One call and the value it returned:
- One error case (the bad input, and the exception raised):
- Proof it is pure (the same call twice giving the same value, or the input
  unchanged after the call):

#!/usr/bin/env python3
"""library.py — YOUR working file: a library of pure functions.

Build this function library one exercise at a time. Each numbered exercise
names exactly what to write, including the docstring it must carry. The
finished reference is in examples/library.py — try each exercise yourself
before peeking.

Rules for every function you write here:
    - Give it a docstring: one line saying what it RETURNS, then a short
      example. The tests check that each public function has a docstring.
    - Make it PURE: take input only from the arguments, return a value, and
      do not print or change anything outside the function.

When all six exercises are done, run:  bash tests/run_tests.sh
"""


def word_count(text):
    """Return the number of whitespace-separated words in text.

    >>> word_count("the quick brown fox")
    4
    """
    # Exercise 1: RETURN A VALUE.
    # Split text on whitespace with text.split() and return how many pieces
    # there are (use len). Do not print — return the number.
    raise NotImplementedError("Exercise 1: implement word_count")


def normalize_whitespace(text):
    """Return text with runs of whitespace collapsed to one space and the
    ends stripped. (Provided as a worked example — read it, then match its
    shape in your own functions.)

    >>> normalize_whitespace("  hello   world  ")
    'hello world'
    """
    return " ".join(text.split())


def reverse_words(text):
    """Return text with its words in reverse order.

    >>> reverse_words("one two three")
    'three two one'
    """
    # Exercise 2: BUILD AND RETURN A STRING.
    # Split text into words, reverse the list (reversed(...) or [::-1]), and
    # join the words back with a single space. Return the joined string.
    raise NotImplementedError("Exercise 2: implement reverse_words")


def celsius_to_fahrenheit(celsius):
    """Return the Fahrenheit value for a Celsius temperature.

    >>> celsius_to_fahrenheit(100)
    212.0
    """
    # Exercise 3: ONE PARAMETER, ONE RETURN.
    # Apply the formula celsius * 9 / 5 + 32 and return the result.
    raise NotImplementedError("Exercise 3: implement celsius_to_fahrenheit")


def clamp(value, low=0.0, high=1.0):
    """Return value limited to the range [low, high], using DEFAULT arguments
    so clamp(x) limits to [0.0, 1.0].

    >>> clamp(1.5)
    1.0
    >>> clamp(-3, low=-10, high=10)
    -3
    """
    # Exercise 4: DEFAULT ARGUMENTS.
    # low and high already have defaults in the signature above — do not
    # change them. Return the value pulled back into range:
    #     max(low, min(value, high))
    raise NotImplementedError("Exercise 4: implement clamp")


def summarize(numbers):
    """Return a tuple (count, total, minimum, maximum, mean) for numbers.

    >>> summarize([2, 4, 6])
    (3, 12, 2, 6, 4.0)
    """
    # Exercise 5: RETURN A TUPLE OF SEVERAL RESULTS.
    # 1. If numbers is empty, raise ValueError("cannot summarize an empty
    #    sequence").
    # 2. Otherwise compute count (len), total (sum), min, max, and the mean
    #    (total / count), and return them as a 5-tuple in that order.
    raise NotImplementedError("Exercise 5: implement summarize")


def tally(items, counts=None):
    """Return a frequency dict counting how often each item appears.

    The default for counts is None, NOT {} — a mutable default would be
    shared across calls and remember old items. Build a fresh dict inside.

    >>> tally(["a", "b", "a"])
    {'a': 2, 'b': 1}
    >>> tally(["a"], {"a": 5})
    {'a': 6}
    """
    # Exercise 6: AVOID THE MUTABLE-DEFAULT TRAP.
    # 1. Start result as a COPY of counts when counts is not None
    #    (result = dict(counts)), otherwise an empty dict {}.
    # 2. For each item, do result[item] = result.get(item, 0) + 1.
    # 3. Return result. (Keep the None default — do not write counts={}.)
    raise NotImplementedError("Exercise 6: implement tally")

#!/usr/bin/env bash
# Tests for the Day 057 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# The library is a set of PURE functions, so the tests are simple: import a
# function, call it, and assert on the value it returns. Every check drives
# real behaviour — return values, a returned tuple, default and keyword
# arguments, purity (calling twice gives the same answer and does not mutate
# the input), the mutable-default-argument trap, and that every public
# function carries a docstring. It first tests the complete reference
# (examples/library.py), then the learner's starter — structurally while the
# exercises are unfinished, and to the same strict standard once they are
# complete. No network, non-interactive. Exits 0 only if every check passes.
set -u

# Keep the working tree clean: no __pycache__ from the imports below.
export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ref_dir="${lab_dir}/examples"
starter_dir="${lab_dir}/starter"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# assert <dir> <label> <python-assertion-body>
# Runs a python snippet with library.py importable from <dir>. A small
# _raises(func, arg) helper is provided for "must raise ValueError" checks.
# The snippet fails the check if it raises anything or exits non-zero.
assert() {
  local dir="$1" label="$2" body="$3"
  if python3 -c "import sys; sys.path.insert(0, '${dir}')
from library import *
def _raises(func, arg):
    try:
        func(arg)
        return False
    except ValueError:
        return True
${body}" 2>/dev/null; then
    check "${label}" "yes"
  else
    check "${label}" "no"
  fi
}

run_library_checks() {
  local dir="$1"
  echo "Testing ${dir}/library.py ..."

  # --- Return values ---
  assert "${dir}" "word_count returns 4"            "assert word_count('the quick brown fox') == 4"
  assert "${dir}" "word_count of blanks returns 0"  "assert word_count('   ') == 0"
  assert "${dir}" "normalize_whitespace collapses"  "assert normalize_whitespace('  a   b  ') == 'a b'"
  assert "${dir}" "reverse_words reverses order"    "assert reverse_words('one two three') == 'three two one'"
  assert "${dir}" "celsius_to_fahrenheit(100)=212"  "assert celsius_to_fahrenheit(100) == 212.0"
  assert "${dir}" "celsius_to_fahrenheit(0)=32"     "assert celsius_to_fahrenheit(0) == 32.0"
  assert "${dir}" "mean([2,4,6]) == 4.0"            "assert mean([2, 4, 6]) == 4.0"

  # --- Default and keyword arguments ---
  assert "${dir}" "clamp uses default range [0,1]"  "assert clamp(1.5) == 1.0"
  assert "${dir}" "clamp with keyword range"        "assert clamp(-3, low=-10, high=10) == -3"
  assert "${dir}" "greet default greeting"          "assert greet('Ada') == 'Hello, Ada!'"
  assert "${dir}" "greet keyword arguments"         "assert greet('Grace', greeting='Welcome', punctuation='.') == 'Welcome, Grace.'"

  # --- Returning a tuple of several results ---
  assert "${dir}" "summarize returns a 5-tuple"     "assert summarize([2, 4, 6]) == (3, 12, 2, 6, 4.0)"
  assert "${dir}" "summarize tuple unpacks"         "c, t, lo, hi, avg = summarize([7, 3, 9]); assert (c, t, lo, hi) == (3, 19, 3, 9)"

  # --- The mutable-default-argument trap is avoided ---
  assert "${dir}" "tally counts frequencies"         "assert tally(['a', 'b', 'a']) == {'a': 2, 'b': 1}"
  assert "${dir}" "tally with a starting count"       "assert tally(['a'], {'a': 5}) == {'a': 6}"
  assert "${dir}" "tally does not leak across calls"  "tally(['x', 'x']); assert tally(['y']) == {'y': 1}"
  assert "${dir}" "tally does not mutate its input"   "start = {'a': 5}; tally(['a'], start); assert start == {'a': 5}"

  # --- Purity: same args -> same result, input unchanged ---
  assert "${dir}" "word_count is pure (repeatable)"  "assert word_count('a b c') == word_count('a b c') == 3"
  assert "${dir}" "summarize does not mutate list"   "data = [3, 1, 2]; summarize(data); assert data == [3, 1, 2]"

  # --- Errors are raised, not hidden ---
  assert "${dir}" "mean([]) raises ValueError"       "assert _raises(mean, [])"
  assert "${dir}" "summarize([]) raises ValueError"  "assert _raises(summarize, [])"

  # --- Every public function carries a docstring ---
  assert "${dir}" "all public functions documented" "import library, inspect
missing = [n for n, f in inspect.getmembers(library, inspect.isfunction) if not (f.__doc__ or '').strip()]
assert not missing, missing"
}

# --- Reference library: always tested strictly ---
run_library_checks "${ref_dir}"

# --- The demo runs and uses the return values ---
echo "Testing examples/demo.py runs ..."
if python3 "${ref_dir}/demo.py" >/dev/null 2>&1; then
  check "demo.py runs and prints results" "yes"
else
  check "demo.py runs and prints results" "no"
fi

# --- Learner starter ---
echo "Testing starter/library.py ..."
if python3 -c "compile(open('${starter_dir}/library.py').read(), 'library.py', 'exec')" 2>/dev/null; then
  check "starter is valid Python" "yes"
else
  check "starter is valid Python" "no"
fi

if grep -q 'NotImplementedError' "${starter_dir}/library.py"; then
  echo "Note: starter/library.py still has unfinished exercises — testing structure only."
  for fn in word_count reverse_words celsius_to_fahrenheit clamp summarize tally; do
    if grep -q "def ${fn}" "${starter_dir}/library.py"; then
      check "starter defines ${fn}" "yes"
    else
      check "starter defines ${fn}" "no"
    fi
  done
else
  run_library_checks "${starter_dir}"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]