Hands-on lab — Day 58: Scope, Closures, and *args/**kwargs

#!/usr/bin/env python3
"""flexible.py — flexible functions with *args, **kwargs, and closures.

A small, self-contained module that demonstrates the Day 58 ideas as working,
testable functions:

  * total(*numbers)               -- variadic positional arguments
  * average(*numbers, ndigits=2)  -- a keyword-only argument
  * make_counter(start, step)     -- a closure with private, remembered state
  * make_multiplier(factor)       -- a closure factory
  * build_request(prompt, **kw)   -- the **kwargs config-merge pattern used by
                                     nearly every ML/LLM library

Every input comes from function arguments (never an interactive prompt), so
the module is fully importable and testable. Run it directly to see a demo:

    python3 flexible.py

Or import a function and use it on its own:

    python3 -c "import sys; sys.path.insert(0, 'examples'); \
from flexible import make_counter; c = make_counter(); print(c(), c(), c())"
"""

# Module-level (global) defaults — the "building stockroom" of settings that
# build_request fills in when the caller does not override them. These mirror
# the generation settings a real LLM call takes (temperature, token budget).
DEFAULTS = {"temperature": 0.7, "max_tokens": 256, "model": "demo"}


def total(*numbers):
    """Return the sum of any number of positional arguments.

    *numbers gathers every positional argument into a tuple, so total() is 0,
    total(5) is 5, and total(2, 4, 6) is 12. Because sum() of an empty tuple
    is 0, the empty case needs no special handling.
    """
    return sum(numbers)


def average(*numbers, ndigits=2):
    """Return the mean of the given numbers, rounded to ndigits.

    ndigits is keyword-only: it sits after the *numbers gather, so it can only
    be passed by name (average(1, 2, 3, ndigits=4)) and a stray positional
    number can never be mistaken for it. An empty call returns 0.0.
    """
    if not numbers:
        return 0.0
    return round(sum(numbers) / len(numbers), ndigits)


def make_counter(start=0, step=1):
    """Return a function that yields start, start+step, start+2*step, ...

    This is a closure: the inner counter() captures the enclosing 'count'
    variable and, via 'nonlocal', updates it in place. Each call to
    make_counter builds a fresh, independent 'count', so two counters never
    interfere with each other.
    """
    count = start

    def counter():
        nonlocal count            # rebind the enclosing count, not a new local
        value = count
        count += step
        return value

    return counter


def make_multiplier(factor):
    """Return a function that multiplies its argument by the captured factor.

    make_multiplier(3) returns a 'triple' function and make_multiplier(10)
    returns a 'tenfold' function; each remembers its own 'factor' because the
    inner multiply() closes over the enclosing scope.
    """
    def multiply(n):
        return n * factor         # 'factor' comes from the enclosing scope

    return multiply


def build_request(prompt, **kwargs):
    """Merge caller keyword arguments over DEFAULTS — the ML config pattern.

    **kwargs gathers every extra keyword argument into a dict. Spreading
    {**DEFAULTS, **kwargs} builds a new dict where the caller's values win,
    because they are applied last. This is exactly how a high-level helper
    accepts generation settings and forwards them to a real model call.
    """
    config = {**DEFAULTS, **kwargs}
    return {"prompt": prompt, **config}


def main():
    """Print a short, deterministic demonstration of every function."""
    print(f"total() -> {total()}")
    print(f"total(2, 4, 6) -> {total(2, 4, 6)}")
    print(f"average(10, 20, 30) -> {average(10, 20, 30)}")
    print(f"average(1, 2, 3, ndigits=4) -> {average(1, 2, 3, ndigits=4)}")

    counter = make_counter()
    print(f"counter: {counter()} {counter()} {counter()} {counter()}")
    other = make_counter(100)
    print(f"second counter is independent: {other()}")

    triple = make_multiplier(3)
    tenfold = make_multiplier(10)
    print(f"triple(5) -> {triple(5)} ; tenfold(5) -> {tenfold(5)}")

    default_request = build_request("hello")
    print(f"build_request('hello') -> {default_request}")
    overridden = build_request("hello", temperature=0.2)
    print(
        "build_request('hello', temperature=0.2) -> "
        f"temperature={overridden['temperature']}, model={overridden['model']}"
    )
    return 0


if __name__ == "__main__":
    main()

lesson_id: D058
day: 58
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-058-scope-closures-and-args-kwargs
  - python3 --version
run_commands:
  - python3 examples/flexible.py
  - python3 -c "import sys; sys.path.insert(0, 'examples'); from flexible import make_counter; c = make_counter(); print(c(), c(), c())"
  - python3 starter/flexible.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/flexible.py  # optional: reset your work'
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 -> 18 checks, 0 failure(s), exit 0'

# Dependencies — Day 058 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 earlier in the
  course.
- `bash` for the test runner (preinstalled on macOS and Linux).
- Only the Python standard library is used — in fact only core language
  features (`*args`, `**kwargs`, closures, `nonlocal`) and no imports at all
  in the module itself. There is deliberately no `requirements.txt`: these
  are built-in language features that run on any plain Python install.

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 module is pure standard-library Python
and behaves identically everywhere.

#!/usr/bin/env python3
"""flexible.py — YOUR working file.

Build these flexible functions one exercise at a time. Each numbered exercise
below names exactly what to write. The finished reference is in
examples/flexible.py — try each exercise yourself before peeking.

When all five exercises are done, running this file prints the same demo as
the reference:

    python3 starter/flexible.py

Then run:  bash tests/run_tests.sh
"""

# Module-level (global) defaults, provided. build_request fills these in when
# the caller does not override them. They mirror LLM generation settings.
DEFAULTS = {"temperature": 0.7, "max_tokens": 256, "model": "demo"}


def total(*numbers):
    """Return the sum of any number of positional arguments."""
    # Exercise 1: VARIADIC POSITIONAL ARGUMENTS.
    # *numbers gathers every positional argument into a tuple. Return their
    # sum. Hint: sum() of an empty tuple is 0, so total() should return 0
    # with no special case.
    raise NotImplementedError("Exercise 1: implement total")


def average(*numbers, ndigits=2):
    """Return the mean of the numbers, rounded to ndigits (keyword-only)."""
    # Exercise 2: A KEYWORD-ONLY ARGUMENT.
    # ndigits sits after *numbers, so it is keyword-only. If there are no
    # numbers, return 0.0. Otherwise return round(sum(numbers)/len(numbers),
    # ndigits).
    raise NotImplementedError("Exercise 2: implement average")


def make_counter(start=0, step=1):
    """Return a function yielding start, start+step, start+2*step, ..."""
    # Exercise 3: A CLOSURE WITH PRIVATE STATE.
    # 1. Set count = start.
    # 2. Define an inner function counter() that:
    #      - declares 'nonlocal count' (so it rebinds the enclosing count),
    #      - remembers the current value, adds step to count, returns the
    #        remembered value.
    # 3. Return the inner counter function (do NOT call it here).
    raise NotImplementedError("Exercise 3: implement make_counter")


def make_multiplier(factor):
    """Return a function that multiplies its argument by the captured factor."""
    # Exercise 4: A CLOSURE FACTORY.
    # Define an inner function multiply(n) that returns n * factor (factor is
    # captured from this enclosing scope), then return multiply.
    raise NotImplementedError("Exercise 4: implement make_multiplier")


def build_request(prompt, **kwargs):
    """Merge caller keyword arguments over DEFAULTS (the ML config pattern)."""
    # Exercise 5: **kwargs CONFIG MERGE.
    # 1. **kwargs gathers extra keyword arguments into a dict.
    # 2. Build config = {**DEFAULTS, **kwargs} so the caller's values win
    #    (they are spread last).
    # 3. Return {"prompt": prompt, **config}.
    raise NotImplementedError("Exercise 5: implement build_request")


def main():
    """Print a short, deterministic demonstration of every function. (Provided.)"""
    print(f"total() -> {total()}")
    print(f"total(2, 4, 6) -> {total(2, 4, 6)}")
    print(f"average(10, 20, 30) -> {average(10, 20, 30)}")
    print(f"average(1, 2, 3, ndigits=4) -> {average(1, 2, 3, ndigits=4)}")

    counter = make_counter()
    print(f"counter: {counter()} {counter()} {counter()} {counter()}")
    other = make_counter(100)
    print(f"second counter is independent: {other()}")

    triple = make_multiplier(3)
    tenfold = make_multiplier(10)
    print(f"triple(5) -> {triple(5)} ; tenfold(5) -> {tenfold(5)}")

    default_request = build_request("hello")
    print(f"build_request('hello') -> {default_request}")
    overridden = build_request("hello", temperature=0.2)
    print(
        "build_request('hello', temperature=0.2) -> "
        f"temperature={overridden['temperature']}, model={overridden['model']}"
    )
    return 0


if __name__ == "__main__":
    main()

# Flexible-functions design worksheet

Fill this in *before* writing code for the practice assignment. Designing each
function on paper first — its signature, what it gathers or captures, and its
edge cases — is exactly the discipline this lesson teaches. One row per
function.

## The functions

| Function | Signature | Uses *args / **kwargs / closure? | What it gathers or captures | Returns |
| -------- | --------- | -------------------------------- | --------------------------- | ------- |
| (variadic aggregator) |  |  |  |  |
| (closure factory)     |  |  |  |  |
| (**kwargs config merge) |  |  |  |  |

## Calls and edge cases

For each function, write one ordinary call and one edge case (empty input, an
override, or a second independent instance) with the value you expect.

1. Aggregator — good call / edge case:
2. Closure factory — good call / edge case (prove it remembers state or that two
   instances are independent):
3. Config merge — good call / edge case (an override that wins over a default):

## Scope check

For your closure factory, answer in one line each:

- What variable does the inner function capture, and from which scope?
- Does the inner function need `nonlocal`? Why or why not?
- Do two instances made by two factory calls share state or not? Why?

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

- The demo output of `python3 <your-file>.py`:
- The three `assert` lines you wrote and that they all passed (script exited 0):

#!/usr/bin/env bash
# Tests for the Day 058 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the reference module (examples/flexible.py) by importing its
# functions and asserting their behaviour: variadic total, keyword-only
# average, the make_counter closure (private, independent state), the
# make_multiplier factory, and the build_request **kwargs config merge. It
# also runs the module demo and checks its output, confirms DEFAULTS is not
# mutated, and finally checks the learner's starter — structurally while the
# exercises are unfinished, and to the same strict standard once complete.
# No network, non-interactive. Exits 0 only if every check passes.
set -u

# Keep the working tree clean: do not let imported modules write __pycache__.
export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ref_dir="${lab_dir}/examples"
starter_dir="${lab_dir}/starter"
ref="${ref_dir}/flexible.py"
starter="${starter_dir}/flexible.py"
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
}

# check_py <label> <module_dir> <python-body>
# Imports 'flexible' from module_dir and runs the assertion body; passes when
# python3 exits 0.
check_py() {
  local label="$1" mod_dir="$2" body="$3"
  if python3 -c "import sys; sys.path.insert(0, '${mod_dir}'); import flexible
${body}" 2>/dev/null; then
    check "${label}" "yes"
  else
    check "${label}" "no"
  fi
}

run_fn_checks() {
  local mod_dir="$1"
  echo "Testing functions imported from ${mod_dir}/flexible.py ..."
  check_py "total() is 0 and total(2,4,6) is 12" "${mod_dir}" \
    "assert flexible.total() == 0; assert flexible.total(2, 4, 6) == 12"
  check_py "average(10,20,30) is 20.0 and empty is 0.0" "${mod_dir}" \
    "assert flexible.average(10, 20, 30) == 20.0; assert flexible.average() == 0.0"
  check_py "average ndigits is keyword-only" "${mod_dir}" \
    "assert flexible.average(1, 2, 3, ndigits=4) == 2.0; assert flexible.average(1, 2, 3, 4) == 2.5"
  check_py "make_counter yields 0,1,2 (private state)" "${mod_dir}" \
    "c = flexible.make_counter(); assert [c(), c(), c()] == [0, 1, 2]"
  check_py "two counters are independent" "${mod_dir}" \
    "c = flexible.make_counter(); d = flexible.make_counter(100); assert c() == 0; assert d() == 100; assert c() == 1"
  check_py "make_counter respects start and step" "${mod_dir}" \
    "e = flexible.make_counter(10, 5); assert [e(), e(), e()] == [10, 15, 20]"
  check_py "make_multiplier captures its own factor" "${mod_dir}" \
    "t = flexible.make_multiplier(3); x = flexible.make_multiplier(10); assert t(5) == 15; assert x(5) == 50"
  check_py "build_request fills all defaults" "${mod_dir}" \
    "r = flexible.build_request('hello'); assert r == {'prompt': 'hello', 'temperature': 0.7, 'max_tokens': 256, 'model': 'demo'}"
  check_py "build_request lets caller override, model kept" "${mod_dir}" \
    "r = flexible.build_request('hi', temperature=0.2, max_tokens=500); assert r['temperature'] == 0.2 and r['max_tokens'] == 500 and r['model'] == 'demo'"
  check_py "build_request does not mutate DEFAULTS" "${mod_dir}" \
    "flexible.build_request('hi', temperature=0.2); assert flexible.DEFAULTS == {'temperature': 0.7, 'max_tokens': 256, 'model': 'demo'}"
}

# check_demo <label> <script> <needle>
check_demo() {
  local label="$1" script="$2" needle="$3"
  local out
  out="$(python3 "${script}" 2>&1)"
  if printf '%s' "${out}" | grep -qF "${needle}"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
    echo "    (output: ${out})"
  fi
}

run_demo_checks() {
  local script="$1"
  echo "Testing the demo of ${script} ..."
  check_demo "demo prints total(2, 4, 6) -> 12"      "${script}" "total(2, 4, 6) -> 12"
  check_demo "demo prints counter: 0 1 2 3"          "${script}" "counter: 0 1 2 3"
  check_demo "demo prints triple(5) -> 15"           "${script}" "triple(5) -> 15"
  check_demo "demo prints the default request dict"  "${script}" "'model': 'demo'"
}

# --- Reference module: always tested strictly ---
run_fn_checks "${ref_dir}"
run_demo_checks "${ref}"

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

if grep -q 'NotImplementedError' "${starter}"; then
  echo "Note: starter/flexible.py still has unfinished exercises — testing structure only."
  grep -q 'def total' "${starter}"        && check "starter defines total" "yes"        || check "starter defines total" "no"
  grep -q 'def make_counter' "${starter}" && check "starter defines make_counter" "yes" || check "starter defines make_counter" "no"
  grep -q 'def build_request' "${starter}" && check "starter defines build_request" "yes" || check "starter defines build_request" "no"
else
  run_fn_checks "${starter_dir}"
  run_demo_checks "${starter}"
  grep -q 'nonlocal' "${starter}" && check "starter uses nonlocal in the closure" "yes" || check "starter uses nonlocal in the closure" "no"
fi

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