Hands-on lab — Day 51: Loops: for, while, and Iteration Patterns

#!/usr/bin/env python3
"""Iteration Patterns Workbench — a complete, small, real program.

Demonstrates the five core loop patterns on a sequence of whole numbers:

    accumulate  — build a running total and count
    filter      — keep the items that pass a test
    transform   — make a new item from each old one
    search      — scan with an early break, and report the work done
    histogram   — build a small text histogram (counts of each value)

Numbers are read from standard input (whitespace-separated), except the
`demo` command, which uses a built-in sample list so it needs no input.

Usage:
    python3 patterns.py demo                     # show all five patterns
    echo "3 1 4 1 5 9 2 6" | python3 patterns.py total
    echo "3 1 4 1 5 9 2 6" | python3 patterns.py filter 4
    echo "3 1 4 1 5 9 2 6" | python3 patterns.py transform
    echo "3 1 4 1 5 9 2 6" | python3 patterns.py search 5
    echo "1 2 2 3 3 3"     | python3 patterns.py histogram

Bad input (a non-number token, an unknown command, or a missing argument)
prints a clear error to standard error and exits with a non-zero code.
"""
import sys

SAMPLE = [3, 1, 4, 1, 5, 9, 2, 6]


def read_numbers(text):
    """Parse whitespace-separated whole numbers from text into a list of int.

    Raises ValueError naming the first token that is not a whole number.
    """
    numbers = []
    for token in text.split():
        try:
            numbers.append(int(token))
        except ValueError:
            raise ValueError(f"'{token}' is not a whole number")
    return numbers


def accumulate_total(numbers):
    """Accumulator pattern: return (count, total) built one item per pass."""
    count = 0
    total = 0
    for n in numbers:
        count = count + 1
        total = total + n
    return count, total


def filter_above(numbers, threshold):
    """Filter pattern: return the items strictly greater than threshold."""
    kept = []
    for n in numbers:
        if n > threshold:
            kept.append(n)
    return kept


def transform_squares(numbers):
    """Transform pattern: return a new list with each item squared."""
    squares = []
    for n in numbers:
        squares.append(n * n)
    return squares


def linear_search(numbers, target):
    """Search pattern with early break.

    Return (index, comparisons): index is the position of the first item
    equal to target, or -1 if absent; comparisons is how many items were
    inspected — fewer when the target is found early, thanks to break.
    """
    comparisons = 0
    for index, n in enumerate(numbers):
        comparisons = comparisons + 1
        if n == target:
            return index, comparisons
    return -1, comparisons


def build_histogram(numbers):
    """Build a text histogram: for each distinct value, a bar of '#' per count.

    Returns a list of aligned label-and-bar strings, sorted by value.
    """
    counts = {}
    for n in numbers:
        counts[n] = counts.get(n, 0) + 1
    if not counts:
        return []
    width = max(len(str(value)) for value in counts)
    rows = []
    for value in sorted(counts):
        bar = ""
        for _ in range(counts[value]):
            bar = bar + "#"
        rows.append(f"{str(value).rjust(width)} | {bar}")
    return rows


def run_command(command, args, numbers):
    """Dispatch one command. Returns (lines_to_print, exit_code)."""
    if command == "total":
        count, total = accumulate_total(numbers)
        return [f"count={count} sum={total}"], 0

    if command == "filter":
        if len(args) != 1:
            raise ValueError("filter needs one threshold, e.g. filter 4")
        threshold = int_arg(args[0], "threshold")
        return [str(filter_above(numbers, threshold))], 0

    if command == "transform":
        return [str(transform_squares(numbers))], 0

    if command == "search":
        if len(args) != 1:
            raise ValueError("search needs one target, e.g. search 5")
        target = int_arg(args[0], "target")
        index, comparisons = linear_search(numbers, target)
        if index == -1:
            return [f"{target} not found after {comparisons} comparisons"], 1
        return [f"found {target} at index {index} after {comparisons} comparisons"], 0

    if command == "histogram":
        return build_histogram(numbers), 0

    raise ValueError(f"unknown command '{command}'")


def int_arg(text, name):
    """Parse a command argument to int, raising a clear ValueError on failure."""
    try:
        return int(text)
    except ValueError:
        raise ValueError(f"{name} must be a whole number, not '{text}'")


def demo():
    """Run every pattern on the built-in SAMPLE list; needs no input."""
    numbers = SAMPLE
    count, total = accumulate_total(numbers)
    lines = [
        f"sample: {numbers}",
        f"total    -> count={count} sum={total}",
        f"filter>4 -> {filter_above(numbers, 4)}",
        f"transform-> {transform_squares(numbers)}",
    ]
    index, comparisons = linear_search(numbers, 5)
    lines.append(
        f"search 5 -> found 5 at index {index} after {comparisons} comparisons"
    )
    lines.append("histogram:")
    lines.extend(build_histogram(numbers))
    return lines


def main(argv):
    """Entry point. Returns an exit code: 0 on success, non-zero on error."""
    if len(argv) < 2:
        print("error: no command given", file=sys.stderr)
        print(usage(), file=sys.stderr)
        return 1

    command = argv[1]
    args = argv[2:]

    if command in ("-h", "--help", "help"):
        print(usage())
        return 0

    if command == "demo":
        for line in demo():
            print(line)
        return 0

    try:
        numbers = read_numbers(sys.stdin.read())
        lines, code = run_command(command, args, numbers)
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        print(usage(), file=sys.stderr)
        return 1

    for line in lines:
        print(line)
    return code


def usage():
    """Return the one-block usage string."""
    return (
        "usage: python3 patterns.py <command> [arg]\n"
        "  commands (read numbers from stdin, except demo):\n"
        "    demo                 show all five patterns on a sample list\n"
        "    total                accumulate: print count and sum\n"
        "    filter <threshold>   keep items greater than threshold\n"
        "    transform            square each item\n"
        "    search <target>      find target with an early break\n"
        "    histogram            counts of each value as '#' bars"
    )


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

lesson_id: D051
day: 51
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-051-loops-for-while-and-iteration-patterns
  - python3 --version
run_commands:
  - python3 examples/patterns.py demo
  - echo "3 1 4 1 5 9 2 6" | python3 examples/patterns.py total
  - echo "3 1 4 1 5 9 2 6" | python3 examples/patterns.py filter 4
  - echo "3 1 4 1 5 9 2 6" | python3 examples/patterns.py search 5
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/patterns.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 051 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 — specifically the `sys` module,
  which ships with Python. There is deliberately no `requirements.txt`: an
  iteration workbench should run on a plain Python install with nothing to
  install 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. Because the data commands read from
standard input, pipe input with `echo "..." | python3 ...` rather than typing
it interactively.

# Iteration pattern worksheet — Day 051

Use this sheet for the **practice assignment**: design a sixth pattern of
your own *before* you code it, then record how it behaved. Designing the loop
on paper first is the habit that prevents infinite loops and off-by-one
errors. Keep this file — the collections you meet on Days 52-54 give you
richer things to iterate over with exactly these patterns.

## 1. What one job does your new pattern do?

One sentence:

> _e.g. Report the largest number and the index where it first appeared._

## 2. Which loop shape, and why?

- [ ] `for` loop — I am visiting each item of a known collection once
- [ ] `while` loop — I am repeating until a condition becomes false

Reason:

> _________________________________________________________________________

## 3. Accumulator design

| Question | Answer |
| -------- | ------ |
| What variable(s) build up the result? |  |
| What neutral value does each start at? (0, "", [], None, ...) |  |
| What happens to it on each pass? |  |
| Do you `break` early? If so, on what condition? |  |

## 4. Inputs and outputs

- Input source (stdin / a fixed sample / argv): ____________________
- On success, it prints: ____________________  (exit code ____)
- On bad input, it prints (to stderr): ____________________  (exit code ____)

## 5. Edge cases — at least two

| Edge case | What the loop should do |
| --------- | ----------------------- |
| empty input (no numbers) |  |
| a single-item input |  |
| _(your choice)_ |  |

## 6. Behaviour on real inputs (fill in after building)

- One NORMAL input you ran: `___________________`
  - What it printed: `___________________`
  - Exit code: ____
- One EDGE-CASE input you ran: `___________________`
  - What it printed: `___________________`
  - Exit code: ____

## 7. Cost check

If your pattern used a nested loop, how many times would the inner body run
on an input of N items? (Use the outer-times-inner rule.)

> _________________________________________________________________________

#!/usr/bin/env python3
"""Iteration Patterns Workbench — YOUR working file.

Complete the five numbered exercises below, one per loop pattern. Each stub
raises NotImplementedError until you finish it. The finished reference is in
examples/patterns.py — try each exercise yourself before peeking.

When all five are done, this file behaves just like the reference:

    python3 starter/patterns.py demo
    echo "3 1 4 1 5 9 2 6" | python3 starter/patterns.py total   -> count=8 sum=31

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

SAMPLE = [3, 1, 4, 1, 5, 9, 2, 6]


def read_numbers(text):
    """Parse whitespace-separated whole numbers into a list of int.

    Raises ValueError naming the first token that is not a whole number.
    (Provided — study how the loop validates each token at the boundary.)
    """
    numbers = []
    for token in text.split():
        try:
            numbers.append(int(token))
        except ValueError:
            raise ValueError(f"'{token}' is not a whole number")
    return numbers


def accumulate_total(numbers):
    """Accumulator pattern: return (count, total)."""
    # Exercise 1: ACCUMULATE.
    # Start count and total at 0 (the neutral values). Loop over `numbers`
    # with a for loop; each pass, add 1 to count and add the item to total.
    # Return (count, total). Verify by hand: [3,1,4,1,5,9,2,6] -> (8, 31).
    raise NotImplementedError("Exercise 1: implement accumulate_total")


def filter_above(numbers, threshold):
    """Filter pattern: return the items strictly greater than threshold."""
    # Exercise 2: FILTER.
    # Start with an empty list `kept`. Loop over `numbers`; if an item is
    # greater than `threshold`, append it to `kept`. Return `kept`.
    # Example: filter_above([3,1,4,1,5,9,2,6], 4) -> [5, 9, 6].
    raise NotImplementedError("Exercise 2: implement filter_above")


def transform_squares(numbers):
    """Transform pattern: return a new list with each item squared."""
    # Exercise 3: TRANSFORM.
    # Start with an empty list. Loop over `numbers`; append n * n for each n.
    # Example: transform_squares([3,1,4]) -> [9, 1, 16].
    raise NotImplementedError("Exercise 3: implement transform_squares")


def linear_search(numbers, target):
    """Search pattern with early break.

    Return (index, comparisons): index of the first item equal to target,
    or -1 if absent; comparisons is how many items were inspected.
    """
    # Exercise 4: SEARCH WITH EARLY BREAK.
    # Count comparisons starting at 0. Loop with enumerate(numbers); each
    # pass, add 1 to comparisons. As soon as an item equals `target`, RETURN
    # (index, comparisons) immediately (this is the early exit — do not keep
    # scanning). If the loop finishes without a match, return (-1, comparisons).
    raise NotImplementedError("Exercise 4: implement linear_search")


def build_histogram(numbers):
    """Build a text histogram: for each distinct value, a bar of '#' per count."""
    # Exercise 5: HISTOGRAM (accumulate counts, then build bars).
    # 1. Build a dict `counts` mapping each value to how many times it appears
    #    (loop over numbers; counts[n] = counts.get(n, 0) + 1).
    # 2. If counts is empty, return [].
    # 3. Let width = the length of the widest value's text (for alignment).
    # 4. For each value in sorted(counts), build a bar of counts[value] '#'
    #    characters and append f"{str(value).rjust(width)} | {bar}" to a list.
    # Return the list. Example on [1,2,2,3,3,3]: ['1 | #', '2 | ##', '3 | ###'].
    raise NotImplementedError("Exercise 5: implement build_histogram")


# ---------------------------------------------------------------------------
# Everything below is provided: command dispatch, main, and usage. Once the
# five functions above work, the whole program runs like the reference.
# ---------------------------------------------------------------------------


def int_arg(text, name):
    """Parse a command argument to int, raising a clear ValueError on failure."""
    try:
        return int(text)
    except ValueError:
        raise ValueError(f"{name} must be a whole number, not '{text}'")


def run_command(command, args, numbers):
    """Dispatch one command. Returns (lines_to_print, exit_code)."""
    if command == "total":
        count, total = accumulate_total(numbers)
        return [f"count={count} sum={total}"], 0
    if command == "filter":
        if len(args) != 1:
            raise ValueError("filter needs one threshold, e.g. filter 4")
        return [str(filter_above(numbers, int_arg(args[0], "threshold")))], 0
    if command == "transform":
        return [str(transform_squares(numbers))], 0
    if command == "search":
        if len(args) != 1:
            raise ValueError("search needs one target, e.g. search 5")
        index, comparisons = linear_search(numbers, int_arg(args[0], "target"))
        if index == -1:
            return [f"{args[0]} not found after {comparisons} comparisons"], 1
        return [f"found {args[0]} at index {index} after {comparisons} comparisons"], 0
    if command == "histogram":
        return build_histogram(numbers), 0
    raise ValueError(f"unknown command '{command}'")


def demo():
    """Run every pattern on the built-in SAMPLE list; needs no input."""
    numbers = SAMPLE
    count, total = accumulate_total(numbers)
    lines = [
        f"sample: {numbers}",
        f"total    -> count={count} sum={total}",
        f"filter>4 -> {filter_above(numbers, 4)}",
        f"transform-> {transform_squares(numbers)}",
    ]
    index, comparisons = linear_search(numbers, 5)
    lines.append(f"search 5 -> found 5 at index {index} after {comparisons} comparisons")
    lines.append("histogram:")
    lines.extend(build_histogram(numbers))
    return lines


def usage():
    """Return the one-block usage string."""
    return (
        "usage: python3 patterns.py <command> [arg]\n"
        "  commands (read numbers from stdin, except demo):\n"
        "    demo, total, filter <threshold>, transform, search <target>, histogram"
    )


def main(argv):
    """Entry point. Returns an exit code: 0 on success, non-zero on error."""
    if len(argv) < 2:
        print("error: no command given", file=sys.stderr)
        print(usage(), file=sys.stderr)
        return 1
    command, args = argv[1], argv[2:]
    if command in ("-h", "--help", "help"):
        print(usage())
        return 0
    if command == "demo":
        for line in demo():
            print(line)
        return 0
    try:
        numbers = read_numbers(sys.stdin.read())
        lines, code = run_command(command, args, numbers)
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        print(usage(), file=sys.stderr)
        return 1
    for line in lines:
        print(line)
    return code


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

#!/usr/bin/env bash
# Tests for the Day 051 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the complete reference program (examples/patterns.py) on the five
# iteration patterns, feeding numbers on standard input and checking both the
# printed output and the process exit code. It then imports two pattern
# functions and checks their return values, and finally checks the learner's
# starter: 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)"
ref="${lab_dir}/examples/patterns.py"
starter="${lab_dir}/starter/patterns.py"
data="3 1 4 1 5 9 2 6"
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_stdin <label> <script> <input> <expect_exit> <needle> <cmd> [args...]
# Pipes <input> to the program's stdin, checks its exit code and that its
# combined output contains <needle>.
check_stdin() {
  local label="$1" script="$2" input="$3" expect_exit="$4" needle="$5"
  shift 5
  local out code
  out="$(printf '%s' "${input}" | python3 "${script}" "$@" 2>&1)"
  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_program_checks() {
  local script="$1"
  echo "Testing ${script} ..."
  # demo needs no stdin; the rest read numbers from stdin.
  check_stdin "demo shows all patterns" "${script}" ""      0 "count=8 sum=31"          demo
  check_stdin "total (accumulate)"      "${script}" "${data}" 0 "count=8 sum=31"         total
  check_stdin "filter > 4"              "${script}" "${data}" 0 "[5, 9, 6]"              filter 4
  check_stdin "transform (squares)"     "${script}" "${data}" 0 "[9, 1, 16, 1, 25, 81, 4, 36]" transform
  check_stdin "search 5 found early"    "${script}" "${data}" 0 "found 5 at index 4 after 5 comparisons" search 5
  check_stdin "search 7 not found"      "${script}" "${data}" 1 "7 not found after 8 comparisons" search 7
  check_stdin "histogram bars"          "${script}" "1 2 2 3 3 3" 0 "3 | ###"           histogram
  # Bad input is validated at the boundary.
  check_stdin "non-number rejected"     "${script}" "1 x 3"   1 "is not a whole number"  total
  check_stdin "unknown command rejected" "${script}" "1 2 3"  1 "unknown command"        frobnicate
  check_stdin "filter missing arg"      "${script}" "1 2 3"   1 "filter needs one threshold" filter
}

# --- Reference program: always tested strictly ---
run_program_checks "${ref}"

# --- Import functions and check return values (module is importable) ---
echo "Testing importability of examples/patterns.py ..."
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from patterns import accumulate_total; \
assert accumulate_total([3, 1, 4, 1, 5, 9, 2, 6]) == (8, 31)"; then
  check "import accumulate_total -> (8, 31)" "yes"
else
  check "import accumulate_total -> (8, 31)" "no"
fi
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from patterns import linear_search; \
assert linear_search([3, 1, 4, 1, 5], 5) == (4, 5); \
assert linear_search([1, 2, 3], 9) == (-1, 3)"; then
  check "import linear_search early-exit + not-found" "yes"
else
  check "import linear_search early-exit + not-found" "no"
fi

# --- Learner starter ---
echo "Testing starter/patterns.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/patterns.py still has unfinished exercises — testing structure only."
  grep -q 'def accumulate_total' "${starter}" && check "starter defines accumulate_total" "yes" || check "starter defines accumulate_total" "no"
  grep -q 'def build_histogram' "${starter}" && check "starter defines build_histogram" "yes" || check "starter defines build_histogram" "no"
else
  run_program_checks "${starter}"
  grep -q '__name__ == "__main__"' "${starter}" && check "starter has the main guard" "yes" || check "starter has the main guard" "no"
fi

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