Hands-on lab — Day 56: Building a Data-Driven CLI

#!/usr/bin/env python3
"""records.py — a small, data-driven command-line tool.

Manages a list of contact records that persist between runs as a JSON file.
It is a complete rehearsal for the Week 8 project (the Terminal Task
Manager): the same skeleton of argparse subcommands, a JSON store, records
modelled as a list of dicts, and the command -> load -> mutate -> save ->
report loop, with proper exit codes and errors on standard error.

Subcommands:
    add     add a new record
    list    list every record
    find    search records by a field
    delete  remove a record by id

The data file is chosen with the global --store option, which goes BEFORE
the subcommand:

    python3 records.py --store data.json add --name "Ada Lovelace" --email ada@example.com
    python3 records.py --store data.json list
    python3 records.py --store data.json find --field name --query ada
    python3 records.py --store data.json delete --id 1

Input comes entirely from command-line arguments (never an interactive
prompt), so the tool can be tested and automated without a human.
"""
import argparse
import json
import sys


def load_records(path):
    """Return the list of records stored at path.

    A missing file is treated as an empty store (the first run is not an
    error). A file that exists but is not valid JSON, or does not hold a
    JSON list, raises ValueError with a readable message.
    """
    try:
        with open(path, "r", encoding="utf-8") as handle:
            data = json.load(handle)
    except FileNotFoundError:
        return []
    except json.JSONDecodeError as err:
        raise ValueError(f"{path} is not valid JSON ({err})")
    if not isinstance(data, list):
        raise ValueError(f"{path} does not hold a list of records")
    return data


def save_records(path, records):
    """Write records to path as pretty-printed, human-diffable JSON."""
    with open(path, "w", encoding="utf-8") as handle:
        json.dump(records, handle, indent=2, ensure_ascii=False)
        handle.write("\n")


def next_id(records):
    """Return the next id: one more than the largest existing id, or 1."""
    return max((record["id"] for record in records), default=0) + 1


def validate_new(name, email):
    """Raise ValueError if a new record's name or email is unacceptable."""
    if not name.strip():
        raise ValueError("name must not be empty")
    if "@" not in email:
        raise ValueError(f"'{email}' is not a valid email (needs '@')")


def format_record(record):
    """Return the one-line, human-readable form of a record."""
    return f"#{record['id']}: {record['name']} <{record['email']}>"


def cmd_add(args):
    """add: load, append a validated record, save, and report it."""
    records = load_records(args.store)
    validate_new(args.name, args.email)
    record = {
        "id": next_id(records),
        "name": args.name.strip(),
        "email": args.email.strip(),
    }
    records.append(record)
    save_records(args.store, records)
    print(f"added {format_record(record)}")
    return 0


def cmd_list(args):
    """list: print every record, or a clear notice when the store is empty."""
    records = load_records(args.store)
    if not records:
        print("no records")
        return 0
    for record in records:
        print(format_record(record))
    return 0


def cmd_find(args):
    """find: print records whose field contains the query.

    Returns exit code 0 when at least one record matches and 1 when none
    do, so a caller (or a script) can branch on "did we find anything?".
    """
    records = load_records(args.store)
    needle = args.query.lower()
    matches = [
        record
        for record in records
        if needle in str(record.get(args.field, "")).lower()
    ]
    if not matches:
        print(f"no records match {args.field}={args.query!r}", file=sys.stderr)
        return 1
    for record in matches:
        print(format_record(record))
    return 0


def cmd_delete(args):
    """delete: remove the record with the given id, or report it is absent."""
    records = load_records(args.store)
    kept = [record for record in records if record["id"] != args.id]
    if len(kept) == len(records):
        print(f"error: no record with id {args.id}", file=sys.stderr)
        return 1
    save_records(args.store, kept)
    print(f"deleted #{args.id}")
    return 0


def build_parser():
    """Build the argparse parser: a global --store plus four subcommands."""
    parser = argparse.ArgumentParser(
        prog="records.py",
        description="Manage a JSON-backed list of contact records.",
    )
    parser.add_argument(
        "--store",
        default="records.json",
        help="path to the JSON data file (default: records.json)",
    )
    subparsers = parser.add_subparsers(
        dest="command",
        required=True,
        metavar="{add,list,find,delete}",
    )

    add_parser = subparsers.add_parser("add", help="add a new record")
    add_parser.add_argument("--name", required=True, help="the contact's name")
    add_parser.add_argument("--email", required=True, help="the contact's email")
    add_parser.set_defaults(func=cmd_add)

    list_parser = subparsers.add_parser("list", help="list every record")
    list_parser.set_defaults(func=cmd_list)

    find_parser = subparsers.add_parser("find", help="search records by a field")
    find_parser.add_argument(
        "--field",
        default="name",
        choices=["name", "email"],
        help="which field to search (default: name)",
    )
    find_parser.add_argument("--query", required=True, help="text to search for")
    find_parser.set_defaults(func=cmd_find)

    delete_parser = subparsers.add_parser("delete", help="delete a record by id")
    delete_parser.add_argument(
        "--id", type=int, required=True, help="the id of the record to delete"
    )
    delete_parser.set_defaults(func=cmd_delete)

    return parser


def main(argv):
    """Entry point. Parse arguments, dispatch to the chosen command, and
    turn any validation or data error into a clear message plus exit code 1.
    """
    parser = build_parser()
    args = parser.parse_args(argv[1:])
    try:
        return args.func(args)
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        return 1


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

lesson_id: D056
day: 56
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-056-building-a-data-driven-cli
  - python3 --version
run_commands:
  - python3 examples/records.py --store demo.json add --name "Ada Lovelace" --email ada@example.com
  - python3 examples/records.py --store demo.json list
  - python3 examples/records.py --store demo.json find --field name --query ada
  - python3 examples/records.py --store demo.json delete --id 1
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - rm -f demo.json
  - 'git checkout -- starter/records.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 -> 19 checks, 0 failure(s), exit 0'

# Dependencies — Day 056 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 `argparse` and
  `json` (and `sys`), all of which ship with Python. There is deliberately
  no `requirements.txt`: a command-line tool this size 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 itself is pure standard-library
Python and behaves identically everywhere.

# CLI design worksheet

Fill this in *before* writing code for the practice assignment. Designing a
CLI on paper first — its subcommands, arguments, data shape, and exit codes —
is exactly the discipline the lesson teaches. One row per subcommand.

## The tool

- **Name of the tool:**
- **One job it does:**
- **Where the data lives (JSON file path/default):**
- **Shape of one record (the dict keys and their types):**

## Subcommands

| Subcommand | Positional args | Options / flags | What it mutates | Prints (stdout) | Exit code(s) |
| ---------- | --------------- | --------------- | --------------- | --------------- | ------------ |
| add        |                 |                 |                 |                 |              |
| list       |                 |                 |                 |                 |              |
| find       |                 |                 |                 |                 |              |
| delete     |                 |                 |                 |                 |              |

## Validation and errors

List at least three bad inputs the tool must reject, and for each: the
message it prints (to **stderr**) and the exit code it returns.

1.
2.
3.

## Idempotence check

For each subcommand, write whether running it twice with the same arguments
leaves the store in the same state as running it once (idempotent) or not,
and why.

- add:
- list:
- find:
- delete:

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

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

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

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

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

    python3 starter/records.py --store data.json add --name "Ada" --email ada@example.com
    python3 starter/records.py --store data.json list
    python3 starter/records.py --store data.json find --field name --query ada
    python3 starter/records.py --store data.json delete --id 1

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


def load_records(path):
    """Return the list of records stored at path (missing file => empty)."""
    # Exercise 1: LOAD JSON.
    # 1. Open path for reading and use json.load to read the data.
    # 2. If the file does not exist (FileNotFoundError), return [] — the
    #    first run is not an error.
    # 3. If json.load raises json.JSONDecodeError, raise ValueError with a
    #    clear message naming the file.
    # 4. If the data is not a list, raise ValueError.
    # 5. Otherwise return the data.
    raise NotImplementedError("Exercise 1: implement load_records")


def save_records(path, records):
    """Write records to path as pretty-printed JSON. (Provided.)"""
    with open(path, "w", encoding="utf-8") as handle:
        json.dump(records, handle, indent=2, ensure_ascii=False)
        handle.write("\n")


def next_id(records):
    """Return the next id: one more than the largest existing id, or 1."""
    # Exercise 2: COMPUTE THE NEXT ID.
    # Return 1 + the maximum "id" among records, or 1 when records is empty.
    # Hint: max((r["id"] for r in records), default=0) + 1
    raise NotImplementedError("Exercise 2: implement next_id")


def validate_new(name, email):
    """Raise ValueError if a new record's name or email is bad. (Provided.)"""
    if not name.strip():
        raise ValueError("name must not be empty")
    if "@" not in email:
        raise ValueError(f"'{email}' is not a valid email (needs '@')")


def format_record(record):
    """Return the one-line, human-readable form of a record. (Provided.)"""
    return f"#{record['id']}: {record['name']} <{record['email']}>"


def cmd_add(args):
    """add: load, append a validated record, save, and report it."""
    # Exercise 3: THE COMMAND LOOP (load -> mutate -> save -> report).
    # 1. records = load_records(args.store)
    # 2. validate_new(args.name, args.email)
    # 3. build record = {"id": next_id(records), "name": args.name.strip(),
    #    "email": args.email.strip()}
    # 4. append it to records, then save_records(args.store, records)
    # 5. print(f"added {format_record(record)}") and return 0
    raise NotImplementedError("Exercise 3: implement cmd_add")


def cmd_list(args):
    """list: print every record, or a notice when empty. (Provided.)"""
    records = load_records(args.store)
    if not records:
        print("no records")
        return 0
    for record in records:
        print(format_record(record))
    return 0


def cmd_find(args):
    """find: print matching records; exit 0 if any, 1 if none."""
    # Exercise 4: SEARCH WITH EXIT CODES.
    # 1. records = load_records(args.store)
    # 2. needle = args.query.lower()
    # 3. matches = every record where needle is in the chosen field,
    #    compared case-insensitively:
    #        str(record.get(args.field, "")).lower()
    # 4. If there are no matches: print a message to sys.stderr and return 1.
    # 5. Otherwise print each match with format_record and return 0.
    raise NotImplementedError("Exercise 4: implement cmd_find")


def cmd_delete(args):
    """delete: remove the record with the given id, or report it. (Provided.)"""
    records = load_records(args.store)
    kept = [record for record in records if record["id"] != args.id]
    if len(kept) == len(records):
        print(f"error: no record with id {args.id}", file=sys.stderr)
        return 1
    save_records(args.store, kept)
    print(f"deleted #{args.id}")
    return 0


def build_parser():
    """Build the argparse parser: a global --store plus four subcommands. (Provided.)"""
    parser = argparse.ArgumentParser(
        prog="records.py",
        description="Manage a JSON-backed list of contact records.",
    )
    parser.add_argument(
        "--store",
        default="records.json",
        help="path to the JSON data file (default: records.json)",
    )
    subparsers = parser.add_subparsers(
        dest="command",
        required=True,
        metavar="{add,list,find,delete}",
    )

    add_parser = subparsers.add_parser("add", help="add a new record")
    add_parser.add_argument("--name", required=True, help="the contact's name")
    add_parser.add_argument("--email", required=True, help="the contact's email")
    add_parser.set_defaults(func=cmd_add)

    list_parser = subparsers.add_parser("list", help="list every record")
    list_parser.set_defaults(func=cmd_list)

    find_parser = subparsers.add_parser("find", help="search records by a field")
    find_parser.add_argument(
        "--field",
        default="name",
        choices=["name", "email"],
        help="which field to search (default: name)",
    )
    find_parser.add_argument("--query", required=True, help="text to search for")
    find_parser.set_defaults(func=cmd_find)

    delete_parser = subparsers.add_parser("delete", help="delete a record by id")
    delete_parser.add_argument(
        "--id", type=int, required=True, help="the id of the record to delete"
    )
    delete_parser.set_defaults(func=cmd_delete)

    return parser


def main(argv):
    """Entry point: parse arguments, dispatch, and turn errors into exit 1. (Provided.)"""
    parser = build_parser()
    args = parser.parse_args(argv[1:])
    try:
        return args.func(args)
    except ValueError as err:
        print(f"error: {err}", file=sys.stderr)
        return 1


# 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), passing main's return
# value to sys.exit:
#
#     if __name__ == "__main__":
#         sys.exit(main(sys.argv))

#!/usr/bin/env bash
# Tests for the Day 056 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Exercises the complete reference CLI (examples/records.py) against a
# throwaway JSON store: add, list, find (found and not-found), delete
# (present and absent), plus input-validation and corrupt-store errors.
# Every check verifies BOTH the printed output and the process exit code.
# It then imports two functions from the module to check 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

# 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/records.py"
starter="${lab_dir}/starter/records.py"
failures=0
checks=0

# A fresh temporary store per run; removed on exit.
store="$(mktemp -t records-test.XXXXXX)"
rm -f "${store}"                       # start from "no store yet"
cleanup() { rm -f "${store}"; }
trap cleanup EXIT

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 CLI with --store, checks the exit code and that combined output
# contains needle.
check_run() {
  local label="$1" script="$2" expect_exit="$3" needle="$4"
  shift 4
  local out code
  out="$(python3 "${script}" --store "${store}" "$@" 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_cli_checks() {
  local script="$1"
  echo "Testing ${script} ..."
  rm -f "${store}"                              # fresh store for this program
  # Empty store lists cleanly.
  check_run "empty store lists 'no records'" "${script}" 0 "no records" list
  # Add two records: exit 0 and a confirmation line each.
  check_run "add #1 (Ada)"   "${script}" 0 "added #1: Ada Lovelace" add --name "Ada Lovelace" --email ada@example.com
  check_run "add #2 (Alan)"  "${script}" 0 "added #2: Alan Turing"  add --name "Alan Turing"  --email alan@example.com
  # List shows both.
  check_run "list shows Ada"  "${script}" 0 "#1: Ada Lovelace" list
  check_run "list shows Alan" "${script}" 0 "#2: Alan Turing"  list
  # Find: match -> exit 0; no match -> exit 1.
  check_run "find match exits 0"    "${script}" 0 "#1: Ada Lovelace" find --field name --query ada
  check_run "find no-match exits 1" "${script}" 1 "no records match" find --field name --query zoe
  check_run "find by email field"   "${script}" 0 "#2: Alan Turing"  find --field email --query alan@example.com
  # Delete: present -> exit 0; then it is gone; absent -> exit 1.
  check_run "delete #1 exits 0"      "${script}" 0 "deleted #1"          delete --id 1
  check_run "deleted record is gone" "${script}" 1 "no records match"    find --field name --query ada
  check_run "delete absent exits 1"  "${script}" 1 "no record with id 99" delete --id 99
  # Validation: empty name and bad email are rejected with exit 1.
  check_run "empty name rejected" "${script}" 1 "name must not be empty"     add --name "  " --email x@example.com
  check_run "bad email rejected"  "${script}" 1 "is not a valid email"       add --name "Bad" --email noatsign
}

# --- Reference CLI: always tested strictly ---
run_cli_checks "${ref}"

# --- Corrupt store is reported, not crashed (reference only) ---
echo "Testing corrupt-store handling (examples/records.py) ..."
printf 'this is not json {' > "${store}"
corrupt_out="$(python3 "${ref}" --store "${store}" list 2>&1)"
corrupt_code=$?
if [ "${corrupt_code}" -eq 1 ] && printf '%s' "${corrupt_out}" | grep -qF "is not valid JSON"; then
  check "corrupt store -> error, exit 1" "yes"
else
  check "corrupt store -> error, exit 1" "no"
  echo "    (exit ${corrupt_code}; output: ${corrupt_out})"
fi
rm -f "${store}"

# --- Import functions and check return values (main-guard payoff) ---
echo "Testing importability of examples/records.py ..."
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from records import next_id; \
assert next_id([]) == 1; assert next_id([{'id': 4}, {'id': 7}]) == 8"; then
  check "import next_id computes 1 and 8" "yes"
else
  check "import next_id computes 1 and 8" "no"
fi
if python3 -c "import sys; sys.path.insert(0, '${lab_dir}/examples'); \
from records import load_records; \
assert load_records('${lab_dir}/does-not-exist.json') == []"; then
  check "import load_records handles a missing file" "yes"
else
  check "import load_records handles a missing file" "no"
fi

# --- Learner starter ---
echo "Testing starter/records.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/records.py still has unfinished exercises — testing structure only."
  grep -q 'def load_records' "${starter}" && check "starter defines load_records" "yes" || check "starter defines load_records" "no"
  grep -q 'def cmd_add' "${starter}" && check "starter defines cmd_add" "yes" || check "starter defines cmd_add" "no"
else
  run_cli_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 ]