Hands-on lab — Day 54: Tuples, Sets, and Choosing a Collection

#!/usr/bin/env python3
"""Choosing Collections — dedupe items and compute set algebra between two lists.

A complete, small, real program: it reads two comma-separated lists from the
command line, removes duplicates with a set, computes the set algebra between
them (common / only-in-A / only-in-B / symmetric difference), and reports the
results as immutable tuple records.

Usage:
    python3 collections_tool.py "<list A>" "<list B>"

Each list is a comma-separated string of items.

Example:
    python3 collections_tool.py "apple,banana,apple,cherry" "banana,cherry,date,date"
"""
import sys
from collections import namedtuple

# An immutable record of one comparison. namedtuple gives named fields on top
# of a plain tuple: it cannot be changed after creation, so it is a safe
# return value that callers cannot accidentally mutate.
SetReport = namedtuple("SetReport", ["common", "only_in_a", "only_in_b", "symmetric"])


def parse_items(text):
    """Split a comma-separated string into a tuple of cleaned items.

    Returns an immutable tuple (a fixed record of what was read), dropping
    blank entries and trimming surrounding spaces.
    """
    return tuple(part.strip() for part in text.split(",") if part.strip())


def dedupe(items):
    """Return the unique items as a sorted tuple.

    Building a set removes duplicates in one step (membership is O(1)); we
    sort so the output is deterministic, and return a tuple so the result is
    an immutable record.
    """
    return tuple(sorted(set(items)))


def compare(a_items, b_items):
    """Compute set algebra between two item collections.

    Returns an immutable SetReport of sorted tuples:
      common     = A & B  (intersection: in both)
      only_in_a  = A - B  (difference: in A, not B)
      only_in_b  = B - A  (difference: in B, not A)
      symmetric  = A ^ B  (symmetric difference: in exactly one)
    """
    a = set(a_items)
    b = set(b_items)
    return SetReport(
        common=tuple(sorted(a & b)),
        only_in_a=tuple(sorted(a - b)),
        only_in_b=tuple(sorted(b - a)),
        symmetric=tuple(sorted(a ^ b)),
    )


def format_report(a_items, b_items, report):
    """Return the multi-line, human-readable report string."""

    def show(values):
        return ", ".join(values) if values else "(none)"

    lines = [
        f"List A: {len(a_items)} items read, {len(set(a_items))} unique after dedupe",
        f"List B: {len(b_items)} items read, {len(set(b_items))} unique after dedupe",
        f"Common (A & B): {show(report.common)}",
        f"Only in A (A - B): {show(report.only_in_a)}",
        f"Only in B (B - A): {show(report.only_in_b)}",
        f"Symmetric difference (A ^ B): {show(report.symmetric)}",
    ]
    return "\n".join(lines)


def main(argv):
    """Entry point. Returns an exit code: 0 on success, 1 on bad input."""
    if len(argv[1:]) != 2:
        print('error: expected 2 arguments: "<list A>" "<list B>"', file=sys.stderr)
        print('usage: python3 collections_tool.py "a,b,c" "b,c,d"', file=sys.stderr)
        return 1
    a_items = parse_items(argv[1])
    b_items = parse_items(argv[2])
    if not a_items or not b_items:
        print("error: each list must contain at least one item", file=sys.stderr)
        print('usage: python3 collections_tool.py "a,b,c" "b,c,d"', file=sys.stderr)
        return 1
    report = compare(a_items, b_items)
    print(format_report(a_items, b_items, report))
    return 0


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

lesson_id: D054
day: 54
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-054-tuples-sets-and-choosing-a-collection
  - python3 --version
run_commands:
  - python3 examples/collections_tool.py "apple,banana,apple,cherry" "banana,cherry,date,date"
  - python3 examples/collections_tool.py "banana" "banana,cherry"
  - python3 starter/collections_tool.py "apple,banana,apple" "banana,cherry"
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/collections_tool.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 054 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 `sys` (for the
  command line and exit code) and `collections.namedtuple` (for the immutable
  record), both of which ship with Python. There is deliberately no
  `requirements.txt`: choosing collections is core-language work that 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.

# Collection-choice worksheet — Day 054

Choosing the right collection is a design decision you make *before* you code.
For each scenario below, pick ONE of `list`, `tuple`, `set`, or `dict`, and
justify it against the four questions that decide the answer:

1. **Mutable?** Will the data change after you build it?
2. **Ordered / indexed?** Do you need to keep insertion order or reach an item
   by position?
3. **Unique?** Must duplicates be removed automatically?
4. **Fast lookup by key?** Do you need to check membership or fetch a value in
   roughly one step regardless of size?

Fill in a choice and a one-sentence reason for each. There is a model answer
for every row in the instructor solution — try it yourself first.

## Scenarios

| # | Scenario | Your choice | Why (one sentence) |
|---|----------|-------------|--------------------|
| 1 | The (latitude, longitude) of a city, passed around and never changed | | |
| 2 | A growing to-do list the user adds items to and reorders | | |
| 3 | The set of stop-words to strip from text before feeding it to a model | | |
| 4 | A phone book mapping each name to a phone number | | |
| 5 | The unique words (vocabulary) seen while scanning a large document | | |
| 6 | The RGB colour of a pixel, used as a key to count how often it appears | | |
| 7 | An ordered playlist where the same song may appear twice | | |
| 8 | Deduplicating a million scraped URLs, then testing "have I seen this one?" | | |

## Reflection (answer after building the program)

1. Which single property most often decided your answer above — mutability,
   order, uniqueness, or lookup speed? Give an example.

   > 

2. Scenario 6 uses a colour as a **dictionary key**. Why must that key be a
   tuple, not a list? (Hint: hashable.)

   > 

3. In the program you built, `compare()` returns a `SetReport` — an immutable
   tuple record. Name one bug that immutability prevents a caller from causing.

   > 

#!/usr/bin/env python3
"""Choosing Collections — 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/collections_tool.py — try each exercise yourself before peeking.

When you have completed all five exercises, this file should behave just like
the reference:

    python3 starter/collections_tool.py "apple,banana,apple" "banana,cherry"
      ->  a six-line report ending in the symmetric difference

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

# An immutable record of one comparison (a tuple with named fields).
SetReport = namedtuple("SetReport", ["common", "only_in_a", "only_in_b", "symmetric"])


def parse_items(text):
    """Split a comma-separated string into a tuple of cleaned items."""
    # Exercise 1: RETURN AN IMMUTABLE TUPLE.
    # Split `text` on commas, strip spaces off each part, drop blank parts,
    # and return the result as a TUPLE (not a list), e.g.
    #   parse_items("apple, banana ,,apple") -> ("apple", "banana", "apple")
    raise NotImplementedError("Exercise 1: implement parse_items")


def dedupe(items):
    """Return the unique items as a sorted tuple (a set removes duplicates)."""
    # Exercise 2: DEDUPE WITH A SET.
    # Build a set from `items` to drop duplicates, sort it for a deterministic
    # order, and return a tuple, e.g.
    #   dedupe(("a", "a", "b")) -> ("a", "b")
    raise NotImplementedError("Exercise 2: implement dedupe")


def compare(a_items, b_items):
    """Compute set algebra between two item collections; return a SetReport."""
    # Exercise 3: SET ALGEBRA.
    # Turn each argument into a set, then build a SetReport of SORTED TUPLES:
    #   common    = a & b   (intersection)
    #   only_in_a = a - b   (difference)
    #   only_in_b = b - a   (difference)
    #   symmetric = a ^ b   (symmetric difference)
    # Return SetReport(common=..., only_in_a=..., only_in_b=..., symmetric=...).
    raise NotImplementedError("Exercise 3: implement compare")


def format_report(a_items, b_items, report):
    """Return the multi-line, human-readable report string."""
    # Exercise 4: FORMAT OUTPUT.
    # Build a six-line string. Use the helper below so empty groups read
    # "(none)" instead of a blank. The lines are (exact text matters):
    #   List A: <N> items read, <U> unique after dedupe
    #   List B: <N> items read, <U> unique after dedupe
    #   Common (A & B): <items>
    #   Only in A (A - B): <items>
    #   Only in B (B - A): <items>
    #   Symmetric difference (A ^ B): <items>
    # where N is len(a_items), U is len(set(a_items)), and <items> is the
    # comma-joined group from `report`. Return the lines joined by "\n".
    def show(values):
        return ", ".join(values) if values else "(none)"

    raise NotImplementedError("Exercise 4: implement format_report")


def main(argv):
    """Entry point. Returns an exit code: 0 on success, 1 on bad input."""
    if len(argv[1:]) != 2:
        print('error: expected 2 arguments: "<list A>" "<list B>"', file=sys.stderr)
        print('usage: python3 collections_tool.py "a,b,c" "b,c,d"', file=sys.stderr)
        return 1
    a_items = parse_items(argv[1])
    b_items = parse_items(argv[2])
    if not a_items or not b_items:
        print("error: each list must contain at least one item", file=sys.stderr)
        print('usage: python3 collections_tool.py "a,b,c" "b,c,d"', file=sys.stderr)
        return 1
    report = compare(a_items, b_items)
    print(format_report(a_items, b_items, report))
    return 0


# Exercise 5: ADD THE MAIN GUARD.
# Below this comment, add the guard so the program runs only when this file
# is executed directly (not when it is imported):
#
#     if __name__ == "__main__":
#         sys.exit(main(sys.argv))

#!/usr/bin/env bash
# Tests for the Day 054 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the complete reference program (examples/collections_tool.py) on
# known good and bad inputs, checking both the printed output and the process
# exit code, then imports functions from the module and checks their return
# values (dedupe returns an immutable tuple; compare's set algebra is correct).
# 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/collections_tool.py"
starter="${lab_dir}/starter/collections_tool.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} ..."
  # Good input: dedupe count, set algebra, exit 0.
  check_run "A dedupes 4->3"        "${script}" 0 "List A: 4 items read, 3 unique" "apple,banana,apple,cherry" "banana,cherry,date,date"
  check_run "common intersection"   "${script}" 0 "Common (A & B): banana, cherry" "apple,banana,apple,cherry" "banana,cherry,date,date"
  check_run "only in A difference"  "${script}" 0 "Only in A (A - B): apple"       "apple,banana,apple,cherry" "banana,cherry,date,date"
  check_run "only in B difference"  "${script}" 0 "Only in B (B - A): date"        "apple,banana,apple,cherry" "banana,cherry,date,date"
  check_run "symmetric difference"  "${script}" 0 "Symmetric difference (A ^ B): apple, date" "apple,banana,apple,cherry" "banana,cherry,date,date"
  check_run "empty group -> (none)" "${script}" 0 "Only in A (A - B): (none)"      "banana" "banana,cherry"
  # Bad inputs: clear error, non-zero exit.
  check_run "wrong arg count"       "${script}" 1 "expected 2 arguments" "apple,banana"
  check_run "empty list rejected"   "${script}" 1 "at least one item"    " , ," "banana"
}

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

# --- Import functions and check return values (main-guard payoff) ---
echo "Testing importability of examples/collections_tool.py ..."
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from collections_tool import dedupe; \
result = dedupe(('a', 'a', 'b', 'c', 'b')); \
assert result == ('a', 'b', 'c'), result; \
assert isinstance(result, tuple), 'dedupe must return an immutable tuple'"; then
  check "import dedupe returns sorted immutable tuple" "yes"
else
  check "import dedupe returns sorted immutable tuple" "no"
fi
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from collections_tool import compare; \
r = compare(('a', 'b', 'c'), ('b', 'c', 'd')); \
assert r.common == ('b', 'c'), r.common; \
assert r.only_in_a == ('a',), r.only_in_a; \
assert r.symmetric == ('a', 'd'), r.symmetric"; then
  check "import compare set algebra correct" "yes"
else
  check "import compare set algebra correct" "no"
fi

# --- Learner starter ---
echo "Testing starter/collections_tool.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/collections_tool.py still has unfinished exercises — testing structure only."
  # Structural checks while the learner works.
  grep -q 'def parse_items' "${starter}" && check "starter defines parse_items" "yes" || check "starter defines parse_items" "no"
  grep -q 'def compare' "${starter}" && check "starter defines compare" "yes" || check "starter defines compare" "no"
else
  # Learner finished: hold the starter to the same strict standard.
  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 ]