Hands-on lab — Day 63: Designing a Small Program Well

"""summary_core.py — the functional core of the summary tool.

Every function in this module is PURE: it takes values in and returns
values out, with no reading, no printing, no files, and no global state.
That purity is exactly what makes the core easy to test — you call a
function with an example and check what it returns, with no fake files
and no captured output. The messy work of reading arguments, opening
files, and printing lives in the imperative shell (summary.py), never
here. Keeping logic and I/O apart is the single design idea this program
exists to demonstrate.

The tool's job (its spec): turn free-form text full of numbers into a
small statistical summary — count, total, mean, minimum, maximum, and
how many values sit above the mean.
"""


def parse_numbers(text):
    """Parse free-form text into a list of floats.

    Tokens may be separated by commas, spaces, tabs, or newlines. Empty
    or blank text yields an empty list. A token that is not a number
    raises ValueError naming the offending token — the boundary check
    that keeps bad data out of the rest of the core.

    Args:
        text: the raw text to parse.

    Returns:
        A list of floats, one per token, in order.

    Raises:
        ValueError: if any token cannot be read as a number.
    """
    tokens = text.replace(",", " ").split()
    numbers = []
    for token in tokens:
        try:
            numbers.append(float(token))
        except ValueError:
            raise ValueError(f"{token!r} is not a number")
    return numbers


def summarize(numbers):
    """Return summary statistics for a non-empty list of numbers.

    Args:
        numbers: a list of numbers (floats or ints).

    Returns:
        A dict with keys count, total, mean, minimum, maximum, and
        above_mean (how many values are strictly greater than the mean).

    Raises:
        ValueError: if numbers is empty, because a summary of nothing has
            no meaning — the caller must decide what to do about it.
    """
    if not numbers:
        raise ValueError("cannot summarize an empty list of numbers")
    count = len(numbers)
    total = sum(numbers)
    mean = total / count
    above_mean = sum(1 for value in numbers if value > mean)
    return {
        "count": count,
        "total": total,
        "mean": mean,
        "minimum": min(numbers),
        "maximum": max(numbers),
        "above_mean": above_mean,
    }


def format_summary(summary):
    """Render a summary dict as an aligned block of human-readable text.

    This is pure string-building: it returns the text rather than
    printing it, so the shell decides where the text goes and the tests
    can check it directly.

    Args:
        summary: a dict as returned by summarize().

    Returns:
        A multi-line string, one statistic per line.
    """
    return "\n".join(
        [
            f"count      {summary['count']}",
            f"total      {summary['total']:.2f}",
            f"mean       {summary['mean']:.2f}",
            f"minimum    {summary['minimum']:.2f}",
            f"maximum    {summary['maximum']:.2f}",
            f"above mean {summary['above_mean']}",
        ]
    )

#!/usr/bin/env python3
"""summary.py — the imperative shell of the summary tool.

This is the ONLY part of the program that touches the outside world. It
reads command-line arguments, opens a file or reads standard input, prints
the result to standard output, prints errors to standard error, and chooses
the exit code. It contains no statistics logic of its own: it calls the
pure functions in summary_core.py and arranges their inputs and outputs.

Because all the messiness lives here and all the logic lives in the core,
the core can be tested with plain function calls while this thin shell just
wires it to the world.

Usage:
    python3 summary.py numbers.txt          # read from a file
    echo "1 2 3 4 5" | python3 summary.py   # read from standard input
"""
import sys

import summary_core


def read_input(argv):
    """Return the raw text to summarize: from a named file, or from stdin.

    This lives in the shell, not the core, because it performs I/O. It is
    the one place in the program that knows where the bytes come from.
    """
    if len(argv) > 1:
        with open(argv[1], "r", encoding="utf-8") as handle:
            return handle.read()
    return sys.stdin.read()


def main(argv):
    """Wire the shell to the core: read input, run the core, print, exit.

    Any error the core raises (bad token, empty input) or the filesystem
    raises (missing file) becomes a clear message on standard error and a
    non-zero exit code, so a script calling this tool can detect failure.
    """
    try:
        text = read_input(argv)
        numbers = summary_core.parse_numbers(text)
        summary = summary_core.summarize(numbers)
    except (ValueError, OSError) as err:
        print(f"error: {err}", file=sys.stderr)
        return 1
    print(summary_core.format_summary(summary))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

lesson_id: D063
day: 63
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-063-designing-a-small-program-well
  - python3 --version
run_commands:
  - echo "10 20 30 40" | python3 examples/summary.py
  - printf "5, 7, 9, 11\n" > scores.txt && python3 examples/summary.py scores.txt && rm -f scores.txt
  - echo "1 two 3" | python3 examples/summary.py
  - PYTHONPATH=examples python3 -c "import summary_core as c; print(c.summarize([2, 4, 6, 8]))"
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - rm -f scores.txt
  - 'git checkout -- starter/summary_core.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 -> 15 checks, 0 failure(s), exit 0'

# Dependencies — Day 063 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 the Python standard library is used — in fact only `sys`, and the
  built-in `float`, `sum`, `min`, and `max`. The pure core uses no imports
  at all. There is deliberately no `requirements.txt`: a small,
  well-designed program 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 tool is pure standard-library Python
and behaves identically everywhere.

# Design worksheet — design it first

Use this for the practice assignment: design a *second* small program on
paper before writing any code, the same way this lab's `summary` tool was
designed. Filling this in first — spec, then modules and signatures, then
which parts are pure — is the whole discipline the lesson teaches. Do not
write a function body until every row below is filled.

## 1. Spec and examples (before any code)

- **One sentence: what does the program do?**
- **Input (what comes in, and from where — argv, a file, stdin):**
- **Output (what goes out, and to where — stdout, exit code):**
- **Three concrete examples** (input → output), including one bad input:
  1. input: … → output: …
  2. input: … → output: …
  3. bad input: … → error message (stderr) and exit code:

## 2. Decompose into functions (signatures before bodies)

One row per function. Mark each **pure** (values in, values out, no I/O)
or **shell** (does I/O). Aim for a pure core and a thin shell.

| Function (name + params) | What it returns | Pure or shell? | One responsibility (one sentence) |
| ------------------------ | --------------- | -------------- | --------------------------------- |
|                          |                 |                |                                   |
|                          |                 |                |                                   |
|                          |                 |                |                                   |
|                          |                 |                |                                   |

## 3. The functional core / imperative shell split

- **Which functions form the pure core (no I/O)?**
- **Which functions form the shell (all the I/O)?**
- **How will you test the core without any files or captured output?**

## 4. Incremental plan (make it work on the simplest case first)

Order the steps you will build and test, smallest working slice first:

1.
2.
3.

## 5. YAGNI check (what you are deliberately NOT building)

List at least two features you could add but will not, because the spec
does not ask for them yet:

- 
- 

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

- One good run (command and its output):
- One bad run (command, stderr message, and `echo $?`):

"""summary_core.py — YOUR working file: the functional core.

The design is already done for you: the module is split into a pure core
(this file) and a thin imperative shell (summary.py, provided complete).
The three functions below are the whole core, and their docstrings — the
signatures and contracts — are written first, on purpose. That is
docstring-driven design: decide what each function promises before you
write a line of its body. Your job is to fill in the bodies so each
function keeps the promise its docstring makes.

Every function here must stay PURE: no print(), no input(), no open(),
no reading argv — just values in and values out. All of that I/O belongs
in summary.py. Purity is why tests/run_tests.sh can check this core with
plain function calls.

Finish the three numbered exercises, then run:  bash tests/run_tests.sh
"""


def parse_numbers(text):
    """Parse free-form text into a list of floats.

    Tokens may be separated by commas, spaces, tabs, or newlines. Empty
    or blank text yields an empty list. A token that is not a number
    raises ValueError naming the offending token.

    >>> parse_numbers("1, 2, 3")
    [1.0, 2.0, 3.0]
    >>> parse_numbers("")
    []
    """
    # Exercise 1: PARSE (a pure boundary check).
    # 1. Turn every comma into a space, then .split() to get tokens.
    # 2. For each token, try float(token) and collect the result.
    # 3. If float(token) raises ValueError, raise ValueError(f"{token!r} is
    #    not a number") so the caller learns which token was bad.
    # 4. Return the list of floats ([] when there are no tokens).
    raise NotImplementedError("Exercise 1: implement parse_numbers")


def summarize(numbers):
    """Return summary statistics for a non-empty list of numbers.

    Returns a dict with keys count, total, mean, minimum, maximum, and
    above_mean (how many values are strictly greater than the mean).
    Raises ValueError if numbers is empty.
    """
    # Exercise 2: SUMMARIZE (pure computation).
    # 1. If numbers is empty, raise ValueError("cannot summarize an empty
    #    list of numbers"). An empty input is the caller's decision, not
    #    something the core should guess about.
    # 2. Compute count, total, mean (= total / count), minimum, maximum.
    # 3. Compute above_mean: how many values are strictly greater than mean.
    #    Hint: sum(1 for value in numbers if value > mean)
    # 4. Return them in a dict with exactly those six keys.
    raise NotImplementedError("Exercise 2: implement summarize")


def format_summary(summary):
    """Render a summary dict as an aligned block of human-readable text.

    Pure string-building: return the text, do not print it. The shell
    decides where the text goes; the tests check the returned string.
    Each of the six statistics goes on its own line. Format the four
    real-valued numbers (total, mean, minimum, maximum) to two decimals
    with :.2f; count and above_mean are plain integers.
    """
    # Exercise 3: FORMAT (pure rendering).
    # Build and return a multi-line string. To match the reference and the
    # tests exactly, use these label widths and this order:
    #     count      <count>
    #     total      <total, 2 decimals>
    #     mean       <mean, 2 decimals>
    #     minimum    <minimum, 2 decimals>
    #     maximum    <maximum, 2 decimals>
    #     above mean <above_mean>
    # Hint: build a list of f-strings and "\n".join(...) them.
    raise NotImplementedError("Exercise 3: implement format_summary")

#!/usr/bin/env python3
"""summary.py — the imperative shell (PROVIDED, complete).

You do not edit this file. It is here so you can see the other half of the
design: the thin shell that does all the I/O and none of the logic. Once
you finish the three exercises in summary_core.py, this shell will run the
whole tool by calling your pure functions.

    echo "1 2 3 4 5" | python3 starter/summary.py
    python3 starter/summary.py numbers.txt
"""
import sys

import summary_core


def read_input(argv):
    """Return the raw text to summarize: from a named file, or from stdin.

    Lives in the shell, not the core, because it performs I/O.
    """
    if len(argv) > 1:
        with open(argv[1], "r", encoding="utf-8") as handle:
            return handle.read()
    return sys.stdin.read()


def main(argv):
    """Read input, run the pure core, print the result, choose the exit code."""
    try:
        text = read_input(argv)
        numbers = summary_core.parse_numbers(text)
        summary = summary_core.summarize(numbers)
    except (ValueError, OSError) as err:
        print(f"error: {err}", file=sys.stderr)
        return 1
    print(summary_core.format_summary(summary))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env bash
# Tests for the Day 063 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# The point of this suite is to show what a well-designed program buys you:
# because the logic lives in a PURE core (summary_core.py) with no I/O, the
# core is tested with plain function calls — no fake files, no captured
# output. The thin imperative shell (summary.py) is then checked end to end
# through stdin, a file, and error cases. Finally the learner's starter is
# checked: structurally while 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

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
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_core <label> <core_dir> <python-body>
# Runs a small assertion body against summary_core imported from core_dir.
# A clean exit (all asserts pass) is a pass.
check_core() {
  local label="$1" core_dir="$2" body="$3"
  if PYTHONPATH="${core_dir}" python3 -c "import summary_core as c
${body}" 2>/dev/null; then
    check "${label}" "yes"
  else
    check "${label}" "no"
  fi
}

# check_shell <label> <shell_script> <expect_exit> <needle> <stdin-text> [file-arg]
check_shell() {
  local label="$1" script="$2" expect_exit="$3" needle="$4" stdin_text="$5" file_arg="${6:-}"
  local out code
  if [ -n "${file_arg}" ]; then
    out="$(python3 "${script}" "${file_arg}" 2>&1)"
  else
    out="$(printf '%s' "${stdin_text}" | python3 "${script}" 2>&1)"
  fi
  code=$?
  if [ "${code}" -eq "${expect_exit}" ] && printf '%s' "${out}" | grep -qF "${needle}"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
    echo "    (exit ${code}, expected ${expect_exit}; output: ${out})"
  fi
}

run_core_checks() {
  local core_dir="$1"
  echo "Testing the pure core in ${core_dir} (plain function calls, no I/O) ..."
  check_core "parse_numbers reads mixed separators" "${core_dir}" \
    "assert c.parse_numbers('1, 2\n3\t4') == [1.0, 2.0, 3.0, 4.0]"
  check_core "parse_numbers of blank text is []" "${core_dir}" \
    "assert c.parse_numbers('   ') == []"
  check_core "parse_numbers rejects a non-number" "${core_dir}" \
    "import summary_core
try:
    c.parse_numbers('1 two 3'); raise SystemExit(1)
except ValueError as e:
    assert 'two' in str(e)"
  check_core "summarize computes the six statistics" "${core_dir}" \
    "s = c.summarize([2, 4, 6, 8])
assert s['count'] == 4 and s['total'] == 20 and s['mean'] == 5.0
assert s['minimum'] == 2 and s['maximum'] == 8 and s['above_mean'] == 2"
  check_core "summarize rejects an empty list" "${core_dir}" \
    "try:
    c.summarize([]); raise SystemExit(1)
except ValueError:
    pass"
  check_core "format_summary returns aligned text" "${core_dir}" \
    "text = c.format_summary(c.summarize([10, 20, 30]))
assert 'count      3' in text
assert 'mean       20.00' in text
assert 'above mean 1' in text"
}

run_shell_checks() {
  local script="$1" core_dir="$2"
  echo "Testing the shell ${script} end to end ..."
  # The shell imports summary_core from its own directory; make sure the
  # matching core is the one next to it by running with that dir on the path.
  local tmpfile
  check_shell "stdin: three numbers summarized" "${script}" 0 "mean       20.00" "10 20 30"
  check_shell "stdin: bad token -> error, exit 1" "${script}" 1 "is not a number" "1 two 3"
  check_shell "stdin: empty input -> error, exit 1" "${script}" 1 "cannot summarize an empty list" ""
  tmpfile="$(mktemp -t summary-test.XXXXXX)"
  printf '5, 7, 9, 11\n' > "${tmpfile}"
  check_shell "file input summarized" "${script}" 0 "count      4" "" "${tmpfile}"
  rm -f "${tmpfile}"
  check_shell "missing file -> error, exit 1" "${script}" 1 "error:" "" "${lab_dir}/no-such-file.txt"
}

# --- Reference: always tested strictly ---
run_core_checks "${lab_dir}/examples"
run_shell_checks "${lab_dir}/examples/summary.py" "${lab_dir}/examples"

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

if grep -q 'NotImplementedError' "${starter_core}"; then
  echo "Note: starter/summary_core.py still has unfinished exercises — testing structure only."
  grep -q 'def parse_numbers' "${starter_core}" && check "starter defines parse_numbers" "yes" || check "starter defines parse_numbers" "no"
  grep -q 'def summarize' "${starter_core}" && check "starter defines summarize" "yes" || check "starter defines summarize" "no"
  grep -q 'def format_summary' "${starter_core}" && check "starter defines format_summary" "yes" || check "starter defines format_summary" "no"
else
  run_core_checks "${lab_dir}/starter"
  run_shell_checks "${lab_dir}/starter/summary.py" "${lab_dir}/starter"
fi

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