Hands-on lab — Day 66: Exceptions and Error Handling Strategy

#!/usr/bin/env python3
"""dispatch_demo.py — the @retry helper shown both ways.

Run it from the lab directory:

    python3 examples/dispatch_demo.py

First it calls dispatch(), which fails twice and then succeeds, so you see
backoff working. Then it calls dispatch_offline(), which never succeeds, so
you see the retries exhausted and DispatchError raised FROM the underlying
ConnectionError — the chained traceback with its
"The above exception was the direct cause of the following exception" line.

Both operations are deterministic: no randomness, no network, no clock
reading. The same run produces the same output every time.
"""

import traceback

import triage

COUNTS = {"immediate": 2, "urgent": 2, "routine": 1}

print("--- dispatch(): flaky, recovers on the third attempt ---")
print(triage.dispatch(COUNTS))

print()
print("--- dispatch_offline(): never recovers, gives up with chaining ---")
try:
    triage.dispatch_offline(COUNTS)
except triage.DispatchError:
    traceback.print_exc()

#!/usr/bin/env python3
"""raw_triage.py — the intake reader with NO error handling at all.

This script exists to be broken. It reads a JSON-lines intake file and adds
up the severity numbers. When anything goes wrong it does nothing about it,
so Python does the only thing it can: it unwinds the call stack and prints
a traceback. Reading those three tracebacks is Exercise 1 of the lab.

    python3 examples/raw_triage.py examples/samples/intake.jsonl
    python3 examples/raw_triage.py examples/samples/no-such-file.jsonl
    python3 examples/raw_triage.py examples/samples/bad-severity.jsonl
    python3 examples/raw_triage.py examples/samples/missing-field.jsonl
"""

import json
import sys


def read_severity(record):
    """Pull the severity out of one decoded record. Raises KeyError/ValueError."""
    return int(record["severity"])


def total_severity(path):
    """Open the file and add up every record's severity. Handles nothing."""
    total = 0
    with open(path, "r", encoding="utf-8") as handle:
        for line in handle:
            line = line.strip()
            if not line:
                continue
            total += read_severity(json.loads(line))
    return total


def main(argv):
    if len(argv) < 2:
        print("usage: python3 raw_triage.py <records.jsonl>", file=sys.stderr)
        return 2
    print("total severity:", total_severity(argv[1]))
    return 0


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

{"id": "P-201", "name": "Ken", "severity": 2}
{"id": "P-202", "name": "Dennis", "severity": "high"}
{"id": "P-203", "name": "Brian", "severity": 4}

{"id": "P-101", "name": "Ada", "severity": 1}
{"id": "P-102", "name": "Grace", "severity": 3}
{"id": "P-103", "name": "Alan", "severity": 5}
{"id": "P-104", "name": "Edsger", "severity": 2}
{"id": "P-105", "name": "Barbara", "severity": 4}

{"id": "P-301", "name": "Katherine", "severity": 1}
{"id": "P-302", "name": "Dorothy"}
{"id": "P-303", "name": "Mary", "severity": 3}

#!/usr/bin/env python3
"""swallowing.py — the SAME reader, wrapped in a bare except. Do not copy this.

This is the "before" picture of the lab: a script that catches everything,
says nothing, and reports success no matter what happened. Run it on a file
that does not exist and it still prints "done" and exits 0 — the failure is
completely invisible to you and to any script that calls it.

    python3 examples/swallowing.py examples/samples/no-such-file.jsonl ; echo "exit: $?"
    python3 examples/swallowing.py examples/samples/bad-severity.jsonl ; echo "exit: $?"

Every line marked WRONG below is an anti-pattern the lesson names. Your job
in the lab is to rebuild this program's error strategy in starter/triage.py.
"""

import json
import sys

total = 0

try:
    path = sys.argv[1]
    with open(path, "r", encoding="utf-8") as handle:
        for line in handle:
            line = line.strip()
            if not line:
                continue
            total += int(json.loads(line)["severity"])
except:  # WRONG: bare except catches everything, including KeyboardInterrupt
    pass  # WRONG: and then says nothing at all about it

print("total severity:", total)
print("done")
sys.exit(0)  # WRONG: reports success whatever happened

#!/usr/bin/env python3
"""triage.py — the same intake reader, with a real error-handling strategy.

The strategy, stated in one place so you can check the code against it:

  * A record that cannot be read is an EXPECTED condition. It is rejected by
    name, logged with its full traceback, and the rest of the file is still
    processed. That is a decision the record loop can actually make.
  * A missing or unreadable intake FILE is a boundary failure. The loader
    does not catch it; it propagates to main(), which reports it and exits
    non-zero. Fail fast where the program can no longer do its job.
  * A transient dispatch failure is retried with backoff. When the retries
    are exhausted the helper raises DispatchError FROM the last underlying
    error, so the traceback keeps the real cause.
  * Nothing is ever caught and silently discarded.

    python3 examples/triage.py examples/samples/intake.jsonl
    python3 examples/triage.py examples/samples/bad-severity.jsonl
    python3 examples/triage.py examples/samples/no-such-file.jsonl ; echo "exit: $?"
"""

import json
import logging
import sys
import time

# Two custom exceptions. A custom exception is just a class that inherits
# from Exception; the two-line form below is the whole of it. Classes get
# their own lesson tomorrow (Day 67) — for today this minimal form is all
# you need, and all you should write.


class RecordError(Exception):
    """One intake record could not be admitted."""


class DispatchError(Exception):
    """Hand-off to the ward system failed after every retry."""


# ---------------------------------------------------------------- pure core


def parse_record(line, line_number):
    """Turn one line of JSON into a validated record dict.

    Returns {"id": str, "severity": int}. Raises RecordError — chained from
    the underlying error with `from` — when the line cannot be used.

    The except clauses are tried in order, so json.JSONDecodeError must come
    before ValueError: JSONDecodeError is a SUBCLASS of ValueError, and the
    broader clause would otherwise shadow it.
    """
    try:
        raw = json.loads(line)
        record = {"id": raw["id"], "severity": int(raw["severity"])}
    except json.JSONDecodeError as err:
        raise RecordError(f"line {line_number}: not valid JSON") from err
    except TypeError as err:
        raise RecordError(f"line {line_number}: expected a JSON object") from err
    except KeyError as err:
        raise RecordError(f"line {line_number}: missing field {err.args[0]!r}") from err
    except ValueError as err:
        raise RecordError(f"line {line_number}: severity is not a whole number") from err
    else:
        # The `else` block holds the code that must run ONLY when the try
        # block raised nothing. Keeping it out of `try` means a KeyError
        # raised by this range check can never be mistaken for a parse error.
        if not 1 <= record["severity"] <= 5:
            raise RecordError(
                f"line {line_number}: severity {record['severity']} is outside 1-5"
            )
        return record


def band(severity):
    """Map a 1-5 severity to a triage band. Pure; 1 is the most urgent."""
    if severity <= 2:
        return "immediate"
    if severity <= 4:
        return "urgent"
    return "routine"


def summarize(records):
    """Count records per triage band. Pure: a list in, a dict out."""
    counts = {"immediate": 0, "urgent": 0, "routine": 0}
    for record in records:
        counts[band(record["severity"])] += 1
    return counts


# ------------------------------------------------------- the retry helper


def retry(attempts=3, base_delay=0.05, sleep=time.sleep):
    """Return a decorator that retries a callable with exponential backoff.

    Only ConnectionError and TimeoutError are retried: they are the errors
    that a later attempt might genuinely survive. A ValueError would fail
    identically forever, so retrying it would only waste time.

    After `attempts` failures the last error is re-raised as DispatchError
    using `raise ... from err`, so the traceback still names the real cause.
    """

    def decorate(function):
        def wrapper(*args, **kwargs):
            last_error = None
            for attempt in range(1, attempts + 1):
                try:
                    return function(*args, **kwargs)
                except (ConnectionError, TimeoutError) as err:
                    last_error = err
                    if attempt == attempts:
                        break
                    delay = base_delay * (2 ** (attempt - 1))
                    print(
                        f"attempt {attempt} failed ({err}); retrying in {delay:.2f}s",
                        file=sys.stderr,
                    )
                    sleep(delay)
            raise DispatchError(
                f"{function.__name__} gave up after {attempts} attempts"
            ) from last_error

        wrapper.__name__ = function.__name__
        wrapper.__doc__ = function.__doc__
        return wrapper

    return decorate


# A deliberately flaky stand-in for a network call. It is DETERMINISTIC on
# purpose: a list records how many times it has been called in this process,
# so it fails exactly twice and then succeeds, every single run.
_DISPATCH_CALLS = []


@retry(attempts=3, base_delay=0.05)
def dispatch(counts):
    """Hand the summary to the ward system. Fails twice, then succeeds."""
    _DISPATCH_CALLS.append(1)
    if len(_DISPATCH_CALLS) < 3:
        raise ConnectionError(f"ward system unavailable (call {len(_DISPATCH_CALLS)})")
    return f"dispatched {sum(counts.values())} record(s) to the ward system"


@retry(attempts=3, base_delay=0.05)
def dispatch_offline(counts):
    """A ward system that is simply down. Every attempt fails."""
    raise ConnectionError("offline ward system never answers")


# ------------------------------------------------------ imperative shell


def load_records(path):
    """Read every line of `path`; return (records, problems).

    Opens a file, so it is part of the shell, not the core. A bad RECORD is
    handled here because here we can do something about it: reject it, log
    it, and keep going. A bad PATH is NOT handled here — FileNotFoundError
    and PermissionError propagate to the caller, which is the only level
    that can decide the program is over.
    """
    records = []
    problems = []
    handle = open(path, "r", encoding="utf-8")
    try:
        for line_number, line in enumerate(handle, start=1):
            line = line.strip()
            if not line:
                continue
            try:
                records.append(parse_record(line, line_number))
            except RecordError as err:
                # logging.exception records the message AND the full chained
                # traceback, at ERROR level. Only ever call it from inside an
                # except block: it reads the exception currently being handled.
                logging.exception("rejected record on line %d", line_number)
                problems.append(str(err))
    finally:
        # finally runs whether the loop finished, returned, or raised, so the
        # file handle is closed on every path out of this function.
        handle.close()
    return records, problems


def main(argv):
    if len(argv) < 2:
        print("usage: python3 triage.py <records.jsonl> [logfile]", file=sys.stderr)
        return 2
    path = argv[1]
    log_path = argv[2] if len(argv) > 2 else "triage.log"
    logging.basicConfig(
        filename=log_path,
        filemode="w",
        level=logging.INFO,
        format="%(levelname)s: %(message)s",
    )
    try:
        records, problems = load_records(path)
    except FileNotFoundError as err:
        # Handled here, at the boundary, because here we can do something:
        # tell the operator which file, and stop with a non-zero exit code.
        print(f"error: no such intake file: {err.filename}", file=sys.stderr)
        logging.exception("intake file missing")
        return 1
    except PermissionError as err:
        print(f"error: cannot read intake file: {err.filename}", file=sys.stderr)
        logging.exception("intake file unreadable")
        return 1
    else:
        counts = summarize(records)
        print(f"admitted {len(records)} record(s), rejected {len(problems)}")
        for name in ("immediate", "urgent", "routine"):
            print(f"{name:<10} {counts[name]}")
        for problem in problems:
            print(f"rejected: {problem}", file=sys.stderr)
        try:
            print(dispatch(counts))
        except DispatchError as err:
            print(f"error: {err}", file=sys.stderr)
            logging.exception("dispatch failed")
            return 1
        logging.info("run complete: %d admitted, %d rejected", len(records), len(problems))
        return 0
    finally:
        # Runs even on the `return 1` above and even on an unhandled error.
        logging.shutdown()


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

lesson_id: D066
day: 66
kind: coding
languages: [python, bash]
setup_commands:
  - cd labs/sections/programming-with-python/day-066-exceptions-and-error-handling-strategy
  - python3 --version
run_commands:
  - python3 examples/raw_triage.py examples/samples/no-such-file.jsonl
  - python3 examples/raw_triage.py examples/samples/bad-severity.jsonl
  - python3 examples/raw_triage.py examples/samples/missing-field.jsonl
  - python3 examples/swallowing.py examples/samples/no-such-file.jsonl
  - python3 examples/triage.py examples/samples/intake.jsonl
  - python3 examples/triage.py examples/samples/missing-field.jsonl
  - python3 examples/triage.py examples/samples/no-such-file.jsonl
  - python3 examples/dispatch_demo.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - rm -f triage.log
  - 'git checkout -- starter/triage.py  # optional: reset your work'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-19'
executed_on: 'macOS (Apple Silicon), Python 3.14.0, bash 3.2.57 — bash tests/run_tests.sh -> 29 checks, 0 failure(s). exit 0'

# Dependencies — Day 066 lab

**Python 3 only. No third-party packages, no network, no API key.**

- `python3` (3.8 or newer; tested on 3.14.0). You set this up on Day 43.
- `bash` for the test runner (preinstalled on macOS and Linux).
- Standard library only: `json`, `logging`, `sys`, `time`, and `traceback`.
  Every one of those ships with Python. There is deliberately no
  `requirements.txt` — error handling is a language feature and a design
  discipline, not something you install.

Check your Python is present and new enough:

```bash
python3 --version
```

If that prints `Python 3.8` or higher you are ready.

## A note on Python versions

Python 3.11 and newer print *fine-grained* tracebacks: under the failing
line you get `~~~^^^` carets pointing at the exact sub-expression that
raised. On 3.8-3.10 those caret lines are simply absent and everything else
is the same. The lab's captured output was taken on 3.14.0, so it shows the
carets; nothing in the tests depends on them.

Exception chaining (`raise ... from err`, `__cause__`, and the
"The above exception was the direct cause of the following exception" line)
has been in Python since 3.0, so it works on every version this course
supports.

## Windows

Run the commands inside WSL and follow the Linux path. Native Windows Python
raises exactly the same exceptions, but the test runner needs `bash`, and
tracebacks print Windows-style paths.

# Exercise 0 — read three real tracebacks

Before you write a single handler, produce the failures and read what Python
tells you about them. Run each command from the lab directory and paste the
traceback it prints into the matching box below, then answer the three
questions under it.

The paths in your tracebacks will be **your** absolute paths, not the ones in
`expected-output/tracebacks.txt` — that file has them shortened to `<lab>` so
it stays readable. The exception type, the message, and the order of the
frames are what must match.

```bash
python3 examples/raw_triage.py examples/samples/no-such-file.jsonl
python3 examples/raw_triage.py examples/samples/bad-severity.jsonl
python3 examples/raw_triage.py examples/samples/missing-field.jsonl
```

---

## 1. `FileNotFoundError`

Command: `python3 examples/raw_triage.py examples/samples/no-such-file.jsonl`

```text
paste the traceback here
```

- Which line of `raw_triage.py` actually raised it?
- How many stack frames are shown, and what does that tell you about how
  the program got there?
- Is this an expected condition or a bug in the program?

## 2. `ValueError`

Command: `python3 examples/raw_triage.py examples/samples/bad-severity.jsonl`

```text
paste the traceback here
```

- What exact value could `int()` not convert, and which record was it in?
- Which function is innermost, and why is it printed last?
- Would retrying this call help? Why not?

## 3. `KeyError`

Command: `python3 examples/raw_triage.py examples/samples/missing-field.jsonl`

```text
paste the traceback here
```

- What is the single quoted word after `KeyError:`, and what does it name?
- The file has three records and the first one is fine. What happened to
  the third record, and why?
- Which level of the program is the right place to handle this: the
  expression that raised it, the loop over records, or `main()`? Say why.

---

## 4. What the bare `except` costs

Now run the swallowing version on the same two bad files and record what it
prints and what it exits with:

```bash
python3 examples/swallowing.py examples/samples/no-such-file.jsonl ; echo "exit: $?"
python3 examples/swallowing.py examples/samples/bad-severity.jsonl ; echo "exit: $?"
```

```text
paste both runs here
```

- What number does it print for the missing file, and why is that number
  worse than a crash?
- A script that runs this program every night checks the exit code to decide
  whether to alert someone. What would that script have concluded?
- Write one sentence naming the difference between an *expected condition*
  and a *bug*, using the three tracebacks above as your examples.

#!/usr/bin/env python3
"""starter/triage.py — YOUR working file: rebuild the error strategy.

The program in examples/swallowing.py "works": it never crashes, it always
prints "done", and it always exits 0. It is also useless, because it hides
every failure — a missing file, a bad number, a missing field, all reported
as success. Your job is to give the same program a real strategy.

The design decisions are already made for you and written into the
docstrings below. Fill in the three numbered exercises so the program keeps
those promises. `main()` is provided complete — read it, do not edit it: it
shows where a boundary failure is handled and why `finally` is there.

Work in this order:

  Exercise 0  reproduce the three tracebacks (see starter/traceback-notes.md)
  Exercise 1  parse_record  — narrow handlers, `else`, and `raise ... from`
  Exercise 2  load_records  — try/finally, and logging.exception
  Exercise 3  retry         — a decorator with backoff that re-raises chained

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

import json
import logging
import sys
import time

# Two custom exceptions, provided. A custom exception is just a class that
# inherits from Exception; this two-line form is the whole of it. Classes get
# their own lesson tomorrow (Day 67) — today you only USE these two.


class RecordError(Exception):
    """One intake record could not be admitted."""


class DispatchError(Exception):
    """Hand-off to the ward system failed after every retry."""


# ---------------------------------------------------------------- pure core


def parse_record(line, line_number):
    """Turn one line of JSON into a validated record dict.

    Returns {"id": <the id>, "severity": <int 1-5>}.
    Raises RecordError, chained from the underlying error, when the line
    cannot be used.
    """
    # Exercise 1: NARROW HANDLERS, `else`, AND CHAINING.
    #
    # 1. In a `try` block, decode and build the record:
    #        raw = json.loads(line)
    #        record = {"id": raw["id"], "severity": int(raw["severity"])}
    #
    # 2. Add FOUR except clauses, each catching one specific thing and
    #    re-raising RecordError with `from err` so the cause is preserved:
    #        except json.JSONDecodeError as err:
    #            raise RecordError(f"line {line_number}: not valid JSON") from err
    #        except TypeError as err:      -> "expected a JSON object"
    #        except KeyError as err:       -> f"missing field {err.args[0]!r}"
    #        except ValueError as err:     -> "severity is not a whole number"
    #
    #    ORDER MATTERS. Clauses are tried top to bottom and the first match
    #    wins, and json.JSONDecodeError is a SUBCLASS of ValueError — so if
    #    you put ValueError first it will shadow the JSON clause and every
    #    malformed line will be reported as a bad severity.
    #
    # 3. Add an `else:` block. Code that must run only when the try block
    #    raised NOTHING belongs there, not in the try:
    #        if not 1 <= record["severity"] <= 5:
    #            raise RecordError(f"line {line_number}: severity "
    #                              f"{record['severity']} is outside 1-5")
    #        return record
    #    (Note this one is raised WITHOUT `from`: there is no underlying
    #     error to chain — the value is simply out of range.)
    raise NotImplementedError("Exercise 1: implement parse_record")


def band(severity):
    """Map a 1-5 severity to a triage band. Pure; 1 is the most urgent."""
    if severity <= 2:
        return "immediate"
    if severity <= 4:
        return "urgent"
    return "routine"


def summarize(records):
    """Count records per triage band. Pure: a list in, a dict out."""
    counts = {"immediate": 0, "urgent": 0, "routine": 0}
    for record in records:
        counts[band(record["severity"])] += 1
    return counts


# ------------------------------------------------------- the retry helper


def retry(attempts=3, base_delay=0.05, sleep=time.sleep):
    """Return a decorator that retries a callable with exponential backoff.

    After `attempts` failures, raise DispatchError FROM the last error.
    """
    # Exercise 3: A RETRY DECORATOR (a plain decorator factory — Day 58).
    #
    # def decorate(function):
    #     def wrapper(*args, **kwargs):
    #         last_error = None
    #         for attempt in range(1, attempts + 1):
    #             try:
    #                 return function(*args, **kwargs)
    #             except (ConnectionError, TimeoutError) as err:
    #                 # Retry ONLY errors a later attempt might survive.
    #                 # A ValueError would fail identically forever.
    #                 last_error = err
    #                 if attempt == attempts:
    #                     break
    #                 delay = base_delay * (2 ** (attempt - 1))
    #                 print(f"attempt {attempt} failed ({err}); "
    #                       f"retrying in {delay:.2f}s", file=sys.stderr)
    #                 sleep(delay)
    #         raise DispatchError(
    #             f"{function.__name__} gave up after {attempts} attempts"
    #         ) from last_error
    #     wrapper.__name__ = function.__name__
    #     wrapper.__doc__ = function.__doc__
    #     return wrapper
    # return decorate
    #
    # Type it out rather than pasting it: the shape (factory -> decorate ->
    # wrapper) is the part worth remembering.
    #
    # Replace the placeholder below with your version.
    def decorate(function):
        def wrapper(*args, **kwargs):
            raise NotImplementedError("Exercise 3: implement the retry decorator")

        return wrapper

    return decorate


# Deterministic stand-ins for a network call: a list counts the calls made in
# this process, so dispatch() fails exactly twice and then succeeds, and
# dispatch_offline() never succeeds. No randomness, so output never varies.
_DISPATCH_CALLS = []


@retry(attempts=3, base_delay=0.05)
def dispatch(counts):
    """Hand the summary to the ward system. Fails twice, then succeeds."""
    _DISPATCH_CALLS.append(1)
    if len(_DISPATCH_CALLS) < 3:
        raise ConnectionError(f"ward system unavailable (call {len(_DISPATCH_CALLS)})")
    return f"dispatched {sum(counts.values())} record(s) to the ward system"


@retry(attempts=3, base_delay=0.05)
def dispatch_offline(counts):
    """A ward system that is simply down. Every attempt fails."""
    raise ConnectionError("offline ward system never answers")


# ------------------------------------------------------ imperative shell


def load_records(path):
    """Read every line of `path`; return (records, problems).

    A bad RECORD is handled here, because here we can do something about it:
    reject it, log it, and carry on with the rest of the file. A bad PATH is
    NOT handled here — it must propagate to main(), the only level that can
    decide the whole run is over.
    """
    records = []
    problems = []
    handle = open(path, "r", encoding="utf-8")
    # Exercise 2: try/finally AND logging.exception.
    #
    # 1. Wrap the loop below in `try:` ... `finally: handle.close()` so the
    #    file is closed on every path out of this function — normal end,
    #    early return, or an exception on the way through.
    #
    # 2. Inside the loop, wrap the parse_record call in its own try/except
    #    that catches ONLY RecordError (never a bare except, never
    #    `except Exception`), and in the handler:
    #        logging.exception("rejected record on line %d", line_number)
    #        problems.append(str(err))
    #    logging.exception writes the message AND the full chained traceback
    #    at ERROR level. Call it only from inside an except block — it reads
    #    the exception currently being handled.
    #
    # Replace the loop below with your version.
    for line_number, line in enumerate(handle, start=1):
        line = line.strip()
        if not line:
            continue
        records.append(parse_record(line, line_number))
    handle.close()
    return records, problems


def main(argv):
    """Provided complete — read it, do not edit it."""
    if len(argv) < 2:
        print("usage: python3 triage.py <records.jsonl> [logfile]", file=sys.stderr)
        return 2
    path = argv[1]
    log_path = argv[2] if len(argv) > 2 else "triage.log"
    logging.basicConfig(
        filename=log_path,
        filemode="w",
        level=logging.INFO,
        format="%(levelname)s: %(message)s",
    )
    try:
        records, problems = load_records(path)
    except FileNotFoundError as err:
        print(f"error: no such intake file: {err.filename}", file=sys.stderr)
        logging.exception("intake file missing")
        return 1
    except PermissionError as err:
        print(f"error: cannot read intake file: {err.filename}", file=sys.stderr)
        logging.exception("intake file unreadable")
        return 1
    else:
        counts = summarize(records)
        print(f"admitted {len(records)} record(s), rejected {len(problems)}")
        for name in ("immediate", "urgent", "routine"):
            print(f"{name:<10} {counts[name]}")
        for problem in problems:
            print(f"rejected: {problem}", file=sys.stderr)
        try:
            print(dispatch(counts))
        except DispatchError as err:
            print(f"error: {err}", file=sys.stderr)
            logging.exception("dispatch failed")
            return 1
        logging.info("run complete: %d admitted, %d rejected", len(records), len(problems))
        return 0
    finally:
        logging.shutdown()


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

#!/usr/bin/env bash
# Tests for the Day 066 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# These checks test BEHAVIOUR, not the presence of files: that the right
# exception type comes out of the right input, that __cause__ carries the
# original error (chaining), that a bad record is rejected while the rest of
# the file still processes, that a missing file exits non-zero, that the
# retry helper backs off and then gives up with the cause preserved, and
# that logging.exception really wrote a chained traceback to the log file.
#
# Everything is deterministic: no randomness, no network, no clock reading.
# Exits 0 only if every check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
samples="${lab_dir}/examples/samples"
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_py <label> <module_dir> <python-body>
# Runs assertions against `triage` imported from module_dir. Any AssertionError
# (or any other exception) fails the check.
check_py() {
  local label="$1" module_dir="$2" body="$3"
  if PYTHONPATH="${module_dir}" python3 -c "import triage
${body}" >/dev/null 2>&1; then
    check "${label}" "yes"
  else
    check "${label}" "no"
  fi
}

# check_run <label> <script> <args...> :: expects exit code in EXPECT_EXIT and
# a substring in EXPECT_TEXT (searched in combined stdout+stderr).
check_run() {
  local label="$1" script="$2" expect_exit="$3" needle="$4"
  shift 4
  local out code logfile
  logfile="$(mktemp -t triage-test.XXXXXX)"
  out="$(python3 "${script}" "$@" "${logfile}" 2>&1)"
  code=$?
  rm -f "${logfile}"
  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_unit_checks() {
  local module_dir="$1"
  echo "Testing the handlers in ${module_dir} (direct calls) ..."

  check_py "parse_record accepts a good line" "${module_dir}" \
    'import json
record = triage.parse_record(json.dumps({"id": "P-1", "name": "Ada", "severity": 3}), 1)
assert record == {"id": "P-1", "severity": 3}, record'

  check_py "missing field -> RecordError chained from KeyError" "${module_dir}" \
    'import json
line = json.dumps({"id": "P-1"})
try:
    triage.parse_record(line, 7)
except triage.RecordError as err:
    assert "line 7" in str(err), str(err)
    assert "severity" in str(err), str(err)
    assert isinstance(err.__cause__, KeyError), err.__cause__
else:
    raise SystemExit("no RecordError raised")'

  check_py "bad severity -> RecordError chained from ValueError" "${module_dir}" \
    'import json
line = json.dumps({"id": "P-1", "severity": "high"})
try:
    triage.parse_record(line, 2)
except triage.RecordError as err:
    assert isinstance(err.__cause__, ValueError), err.__cause__
    assert not isinstance(err.__cause__, json.JSONDecodeError), err.__cause__
else:
    raise SystemExit("no RecordError raised")'

  check_py "malformed JSON -> RecordError chained from JSONDecodeError" "${module_dir}" \
    'import json
try:
    triage.parse_record("this is not json", 4)
except triage.RecordError as err:
    assert "not valid JSON" in str(err), str(err)
    assert isinstance(err.__cause__, json.JSONDecodeError), err.__cause__
else:
    raise SystemExit("no RecordError raised")'

  check_py "out-of-range severity -> RecordError with NO cause" "${module_dir}" \
    'import json
line = json.dumps({"id": "P-1", "severity": 9})
try:
    triage.parse_record(line, 3)
except triage.RecordError as err:
    assert "outside 1-5" in str(err), str(err)
    assert err.__cause__ is None, err.__cause__
else:
    raise SystemExit("no RecordError raised")'

  check_py "band and summarize count the three bands" "${module_dir}" \
    'assert triage.band(1) == "immediate" and triage.band(3) == "urgent" and triage.band(5) == "routine"
counts = triage.summarize([{"severity": 1}, {"severity": 2}, {"severity": 4}, {"severity": 5}])
assert counts == {"immediate": 2, "urgent": 1, "routine": 1}, counts'

  check_py "retry succeeds after two failures, with backoff" "${module_dir}" \
    'calls = []
delays = []
@triage.retry(attempts=3, base_delay=0.05, sleep=delays.append)
def flaky():
    calls.append(1)
    if len(calls) < 3:
        raise ConnectionError("not yet")
    return "ok"
assert flaky() == "ok"
assert len(calls) == 3, calls
assert delays == [0.05, 0.1], delays'

  check_py "retry gives up as DispatchError chained from the last error" "${module_dir}" \
    '@triage.retry(attempts=3, base_delay=0.05, sleep=lambda seconds: None)
def always_down():
    raise ConnectionError("down")
try:
    always_down()
except triage.DispatchError as err:
    assert "3 attempts" in str(err), str(err)
    assert isinstance(err.__cause__, ConnectionError), err.__cause__
else:
    raise SystemExit("no DispatchError raised")'

  check_py "retry does not retry a non-transient error" "${module_dir}" \
    'calls = []
@triage.retry(attempts=3, base_delay=0.05, sleep=lambda seconds: None)
def broken():
    calls.append(1)
    raise ValueError("permanently wrong")
try:
    broken()
except ValueError:
    assert len(calls) == 1, calls
else:
    raise SystemExit("ValueError should have propagated on the first attempt")'
}

run_end_to_end_checks() {
  local script="$1"
  echo "Testing ${script} end to end ..."

  check_run "clean intake: 5 admitted, exit 0" "${script}" 0 "admitted 5 record(s), rejected 0" \
    "${samples}/intake.jsonl"
  check_run "clean intake: two immediate" "${script}" 0 "immediate  2" \
    "${samples}/intake.jsonl"
  check_run "bad severity: rejected by name, rest still processed" "${script}" 0 \
    "rejected: line 2: severity is not a whole number" "${samples}/bad-severity.jsonl"
  check_run "missing field: rejected by name, rest still processed" "${script}" 0 \
    "rejected: line 2: missing field 'severity'" "${samples}/missing-field.jsonl"
  check_run "missing field: 2 admitted, 1 rejected" "${script}" 0 \
    "admitted 2 record(s), rejected 1" "${samples}/missing-field.jsonl"
  check_run "retry backs off before succeeding" "${script}" 0 \
    "retrying in 0.10s" "${samples}/intake.jsonl"
  check_run "missing file: fails fast, exit 1" "${script}" 1 \
    "error: no such intake file" "${samples}/no-such-file.jsonl"

  # No argument at all: the shell prints usage and exits 2.
  local usage_out usage_code
  usage_out="$(python3 "${script}" 2>&1)"
  usage_code=$?
  if [ "${usage_code}" -eq 2 ] && printf '%s' "${usage_out}" | grep -qF "usage: python3 triage.py"; then
    check "no argument: usage message, exit 2" "yes"
  else
    check "no argument: usage message, exit 2" "no"
    echo "    (exit ${usage_code}; output: ${usage_out})"
  fi

  # The log file must contain a real chained traceback written by
  # logging.exception -- not just the message.
  local logfile out
  logfile="$(mktemp -t triage-log.XXXXXX)"
  python3 "${script}" "${samples}/bad-severity.jsonl" "${logfile}" >/dev/null 2>&1
  out="$(cat "${logfile}")"
  printf '%s' "${out}" | grep -qF "ERROR: rejected record on line 2" \
    && check "log: ERROR line for the rejected record" "yes" \
    || check "log: ERROR line for the rejected record" "no"
  printf '%s' "${out}" | grep -qF "Traceback (most recent call last):" \
    && check "log: full traceback recorded" "yes" \
    || check "log: full traceback recorded" "no"
  printf '%s' "${out}" | grep -qF "The above exception was the direct cause of the following exception" \
    && check "log: chaining preserved in the log" "yes" \
    || check "log: chaining preserved in the log" "no"
  printf '%s' "${out}" | grep -qF "ValueError: invalid literal for int()" \
    && check "log: the original ValueError is still there" "yes" \
    || check "log: the original ValueError is still there" "no"
  rm -f "${logfile}"
}

echo "Testing the anti-pattern in examples/swallowing.py ..."
swallow_out="$(python3 "${lab_dir}/examples/swallowing.py" "${samples}/no-such-file.jsonl" 2>&1)"
swallow_code=$?
if [ "${swallow_code}" -eq 0 ] && printf '%s' "${swallow_out}" | grep -qF "done"; then
  check "bare except hides a missing file and still exits 0 (the bug we are fixing)" "yes"
else
  check "bare except hides a missing file and still exits 0 (the bug we are fixing)" "no"
fi

echo "Testing that examples/raw_triage.py really raises the three errors ..."
for pair in "no-such-file.jsonl:FileNotFoundError" "bad-severity.jsonl:ValueError" "missing-field.jsonl:KeyError"; do
  sample="${pair%%:*}"
  wanted="${pair##*:}"
  raw_out="$(python3 "${lab_dir}/examples/raw_triage.py" "${samples}/${sample}" 2>&1)"
  raw_code=$?
  if [ "${raw_code}" -ne 0 ] && printf '%s' "${raw_out}" | grep -qF "${wanted}:"; then
    check "raw_triage on ${sample} raises ${wanted}" "yes"
  else
    check "raw_triage on ${sample} raises ${wanted}" "no"
  fi
done

# --- Reference: always tested strictly ---
run_unit_checks "${lab_dir}/examples"
run_end_to_end_checks "${lab_dir}/examples/triage.py"

# --- Learner starter ---
echo "Testing starter/triage.py ..."
starter="${lab_dir}/starter/triage.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/triage.py still has unfinished exercises — testing structure only."
  grep -q 'def parse_record' "${starter}" && check "starter defines parse_record" "yes" || check "starter defines parse_record" "no"
  grep -q 'def load_records' "${starter}" && check "starter defines load_records" "yes" || check "starter defines load_records" "no"
  grep -q 'def retry' "${starter}" && check "starter defines retry" "yes" || check "starter defines retry" "no"
elif grep -qE '^[[:space:]]*except[[:space:]]*:' "${starter}"; then
  check "starter has no bare except left" "no"
  echo "    (a bare 'except:' is still in starter/triage.py — replace it with narrow handlers)"
else
  check "starter has no bare except left" "yes"
  run_unit_checks "${lab_dir}/starter"
  run_end_to_end_checks "${lab_dir}/starter/triage.py"
fi

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