Hands-on lab — Day 52: Lists in Depth

#!/usr/bin/env python3
"""List Toolkit — five idiomatic list operations, plus a demo pipeline.

This is a complete, small, real program: it exposes a handful of pure list
functions and a `main` that runs them over a sample dataset, printing each
step so you can watch a list being built, sliced, sorted, and transformed.

Every function here returns a NEW list and never changes the list it is
given — that discipline (copy before you mutate) is the whole point of the
lesson, because silent list mutation is one of the most common bugs in
data and machine-learning code.

Usage:
    python3 toolkit.py            # run the demo pipeline

Import and reuse any function:
    from toolkit import dedupe, flatten, sort_by_length, top_n, with_appended
"""
import sys


def dedupe(items):
    """Return a new list with duplicates removed, preserving first-seen order.

    Uses list membership (`in`), which scans the growing result — clear and
    correct. A set would make the membership test faster; you meet sets on
    Day 54.
    """
    result = []
    for item in items:
        if item not in result:      # membership test on a list is O(n)
            result.append(item)
    return result


def flatten(matrix):
    """Flatten one level of nesting: a list of lists into a single new list.

    flatten([[1, 2], [3, 4]]) -> [1, 2, 3, 4]
    """
    result = []
    for row in matrix:
        for item in row:            # iterate the inner list
            result.append(item)
    return result


def sort_by_length(words):
    """Return a NEW list of words sorted by length, shortest first.

    `sorted` returns a new list and leaves the input untouched. The sort is
    stable, so words of equal length keep their original relative order.
    """
    return sorted(words, key=len)


def top_n(numbers, n):
    """Return the n largest numbers, highest first, as a new list.

    Sort a copy in descending order, then slice off the first n.
    """
    return sorted(numbers, reverse=True)[:n]


def with_appended(items, value):
    """Return a NEW list equal to items plus value; the input is unchanged.

    `items[:]` makes a shallow copy first, so appending touches only the copy
    — the caller's original list is protected from surprise mutation.
    """
    result = items[:]               # shallow copy protects the caller's list
    result.append(value)
    return result


def main(argv):
    """Run the demo pipeline over a sample dataset. Returns exit code 0."""
    # BUILD a list of exam scores.
    scores = [88, 72, 95, 72, 60, 95, 81]
    print(f"built:    {scores}")

    # SLICE: top three (sort then slice), every other item, the last two.
    print(f"top 3:    {top_n(scores, 3)}")
    print(f"stride:   {scores[::2]}")
    print(f"last 2:   {scores[-2:]}")

    # SORT with a key: order words by length, stably.
    words = ["pear", "fig", "apple", "kiwi", "plum", "fig"]
    print(f"by len:   {sort_by_length(words)}")

    # TRANSFORM: remove duplicates (order kept) and flatten a matrix.
    print(f"unique:   {dedupe(words)}")
    matrix = [[1, 2, 3], [4, 5, 6]]
    print(f"flat:     {flatten(matrix)}")

    # SAFE COPY: grow a copy, then prove the original was not touched.
    original = [10, 20, 30]
    grown = with_appended(original, 40)
    print(f"grown:    {grown}")
    print(f"original: {original}")
    return 0


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

lesson_id: D052
day: 52
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-052-lists-in-depth
  - python3 --version
run_commands:
  - python3 examples/toolkit.py
  - python3 starter/toolkit.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/toolkit.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 → 13 checks, 0 failure(s), exit 0'

# Dependencies — Day 052 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`: lists
  are a built-in type, so this lab runs 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. The stable-sort behaviour this lab relies on
has been guaranteed by Python since version 3.7, so any supported Python
produces identical output.

#!/usr/bin/env python3
"""List Toolkit — YOUR working file.

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

The golden rule for every function here: return a NEW list, and never change
the list you were given. Copy before you mutate.

When all five exercises are done, run:
    python3 starter/toolkit.py
    bash tests/run_tests.sh
"""
import sys


def dedupe(items):
    """Return a new list with duplicates removed, preserving first-seen order."""
    # Exercise 1: DEDUPE.
    # Build an empty result list. Loop over items; append an item only if it
    # is not already `in` result. Return result.
    # Verify by hand: dedupe([1, 1, 2, 1, 3]) must be [1, 2, 3].
    raise NotImplementedError("Exercise 1: implement dedupe")


def flatten(matrix):
    """Flatten one level of nesting: a list of lists into a single new list."""
    # Exercise 2: FLATTEN.
    # Build an empty result list. Loop over each row in matrix; loop over each
    # item in that row; append the item to result. Return result.
    # Verify by hand: flatten([[1, 2], [3, 4]]) must be [1, 2, 3, 4].
    raise NotImplementedError("Exercise 2: implement flatten")


def sort_by_length(words):
    """Return a NEW list of words sorted by length, shortest first."""
    # Exercise 3: SORT WITH A KEY.
    # Return sorted(words, key=len). `sorted` returns a new list and leaves
    # `words` untouched; the sort is stable, so equal-length words keep order.
    raise NotImplementedError("Exercise 3: implement sort_by_length")


def top_n(numbers, n):
    """Return the n largest numbers, highest first, as a new list."""
    # Exercise 4: SORT THEN SLICE.
    # Sort a copy in descending order (sorted(numbers, reverse=True)), then
    # slice off the first n with [:n]. Return that slice.
    raise NotImplementedError("Exercise 4: implement top_n")


def with_appended(items, value):
    """Return a NEW list equal to items plus value; the input is unchanged."""
    # Exercise 5: COPY BEFORE YOU MUTATE.
    # Make a shallow copy first: result = items[:]. Append value to result.
    # Return result. Do NOT append to `items` directly — that would change the
    # caller's list, the exact bug this lesson is about.
    raise NotImplementedError("Exercise 5: implement with_appended")


def main(argv):
    """Run the demo pipeline over a sample dataset. Returns exit code 0."""
    scores = [88, 72, 95, 72, 60, 95, 81]
    print(f"built:    {scores}")
    print(f"top 3:    {top_n(scores, 3)}")
    print(f"stride:   {scores[::2]}")
    print(f"last 2:   {scores[-2:]}")
    words = ["pear", "fig", "apple", "kiwi", "plum", "fig"]
    print(f"by len:   {sort_by_length(words)}")
    print(f"unique:   {dedupe(words)}")
    matrix = [[1, 2, 3], [4, 5, 6]]
    print(f"flat:     {flatten(matrix)}")
    original = [10, 20, 30]
    grown = with_appended(original, 40)
    print(f"grown:    {grown}")
    print(f"original: {original}")
    return 0


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

#!/usr/bin/env bash
# Tests for the Day 052 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the complete reference program (examples/toolkit.py) on known
# inputs, imports each toolkit function and checks its return value, and — the
# heart of this lab — proves the difference between in-place mutation and
# returning a new list (sorted vs .sort(), aliasing vs copy). Finally it 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

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

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ref="${lab_dir}/examples/toolkit.py"
starter="${lab_dir}/starter/toolkit.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_run <label> <script> <expect_exit> <needle> <arg...>
# Runs the program, checks its exit code equals expect_exit and that its
# combined output contains needle.
check_run() {
  local label="$1" script="$2" expect_exit="$3" needle="$4"
  shift 4
  local out code
  out="$(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} ..."
  check_run "pipeline runs, exit 0"     "${script}" 0 "built:    [88, 72, 95, 72, 60, 95, 81]"
  check_run "top 3 via sort+slice"      "${script}" 0 "top 3:    [95, 95, 88]"
  check_run "stride slice [::2]"        "${script}" 0 "stride:   [88, 95, 60, 81]"
  check_run "negative-index slice [-2:]" "${script}" 0 "last 2:   [95, 81]"
  check_run "stable sort by length"     "${script}" 0 "by len:   ['fig', 'fig', 'pear', 'kiwi', 'plum', 'apple']"
  check_run "order-preserving dedupe"   "${script}" 0 "unique:   ['pear', 'fig', 'apple', 'kiwi', 'plum']"
  check_run "flatten a matrix"          "${script}" 0 "flat:     [1, 2, 3, 4, 5, 6]"
  check_run "copy stayed safe"          "${script}" 0 "original: [10, 20, 30]"
}

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

# --- Import each function and check its return value ---
echo "Testing importability and return values of examples/toolkit.py ..."
if python3 -c "
import sys; sys.path.insert(0, '${lab_dir}/examples'); import toolkit
assert toolkit.dedupe([1, 1, 2, 1, 3]) == [1, 2, 3]
assert toolkit.flatten([[1, 2], [3, 4]]) == [1, 2, 3, 4]
assert toolkit.sort_by_length(['bbb', 'a', 'cc']) == ['a', 'cc', 'bbb']
assert toolkit.top_n([3, 9, 1, 7, 4], 2) == [9, 7]
assert toolkit.with_appended([1, 2], 3) == [1, 2, 3]
"; then
  check "each function returns the expected list" "yes"
else
  check "each function returns the expected list" "no"
fi

# --- The core lesson: in-place mutation vs returning a new list ---
echo "Testing in-place vs new-list behaviour ..."
if python3 -c "
import sys; sys.path.insert(0, '${lab_dir}/examples'); import toolkit
# sorted() returns a NEW list; the original is unchanged.
xs = [3, 1, 2]; ys = sorted(xs)
assert ys == [1, 2, 3] and xs == [3, 1, 2]
# .sort() mutates IN PLACE and returns None.
zs = [3, 1, 2]; ret = zs.sort()
assert ret is None and zs == [1, 2, 3]
# Aliasing: assignment shares one list, so a change shows through both names.
p = [1]; q = p; q.append(2)
assert p == [1, 2]
# A slice copy breaks the alias: the original is protected.
m = [1]; n = m[:]; n.append(2)
assert m == [1] and n == [1, 2]
# with_appended must NOT mutate its input (copy-before-mutate).
a = [1, 2]; b = toolkit.with_appended(a, 3)
assert b == [1, 2, 3] and a == [1, 2]
# dedupe/flatten/sort_by_length/top_n leave their inputs unchanged.
src = [1, 1, 2]; toolkit.dedupe(src); assert src == [1, 1, 2]
nested = [[1], [2]]; toolkit.flatten(nested); assert nested == [[1], [2]]
print('all in-place/new-list assertions passed')
"; then
  check "sorted vs .sort(), aliasing vs copy, no input mutation" "yes"
else
  check "sorted vs .sort(), aliasing vs copy, no input mutation" "no"
fi

# --- Learner starter ---
echo "Testing starter/toolkit.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/toolkit.py still has unfinished exercises — testing structure only."
  grep -q 'def dedupe' "${starter}" && check "starter defines dedupe" "yes" || check "starter defines dedupe" "no"
  grep -q 'def with_appended' "${starter}" && check "starter defines with_appended" "yes" || check "starter defines with_appended" "no"
else
  run_program_checks "${starter}"
  if python3 -c "
import sys; sys.path.insert(0, '${lab_dir}/starter'); import toolkit
a = [1, 2]; b = toolkit.with_appended(a, 3)
assert b == [1, 2, 3] and a == [1, 2]
assert toolkit.dedupe([1, 1, 2]) == [1, 2]
"; then
    check "starter copies before mutating (input unchanged)" "yes"
  else
    check "starter copies before mutating (input unchanged)" "no"
  fi
fi

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