Summary Reports Someone Actually Reads at 8am

By the end of this lesson you can take the accepted records from a run, aggregate them into totals a reader can act on, and build a report that also says what was read, when, and from where, closing with a line that states plainly whether the run's own numbers reconcile - all in an order fixed enough that today's report and yesterday's can be compared line by line.

The previous two lessons produced accepted records, quarantined ones, and counts that reconcile between them. None of that is useful yet to the person who has to act on it, because none of it has been turned into something a person reads. A list of Python dictionaries is not a report; it is the material a report is built from.

A report earns the word by doing three things a bare printout does not. It says what it is a report of - which source, read at what time - so a reader six weeks from now can tell this Tuesday's numbers from last Tuesday's without guessing from a filename. It aggregates, because "province: 812, province: 4, province: 91" read one record at a time tells a reader nothing that "north: 907" does not tell them faster. And it states, in words, whether its own arithmetic works - because a total that was computed from a record silently dropped somewhere upstream looks exactly like a total computed correctly, and the only way to tell them apart is to check.

That third point is the one this lesson exists for. A report is generated by code, and code has beliefs about what happened that are not always the same as what happened. A report that never checks its own reconciliation is a summary of what the code believed the run did - which is a different thing from a summary of what the run actually did, and the difference is invisible until the morning it is not.

The other property worth building in from the start is determinism. Two runs over related data - this week's shipments and last week's - should produce reports whose lines land in the same order for the same reasons, so a person, or a diff tool, can tell a real change from noise in how a dictionary happened to iterate.

A report is a list of lines, built the same way a plan of changes was in an earlier module: as data, before anything is printed. Building the whole thing first, then printing it, is what makes it possible to test - a test can inspect the list of lines directly, without capturing standard output.

Every report opens with what it is a report of. At minimum: the source it read, and when it ran. Six weeks from now, a report with no source line and no timestamp is indistinguishable from any other run over any other data, and a reader has no way to know whether they are looking at today's numbers or an old one still open in a tab.

State the counts, then check them against each other. read, accepted, and quarantined are three numbers the previous lesson already produces. The report's job is to print all three and then compute reconciled: read == accepted + quarantined directly from them, rather than assuming it and printing True because the code that got this far presumably worked. A report that skips this line is claiming success by omission; one that includes it is making a checkable claim.

Aggregate from the accepted records, not from a count carried alongside them. len(accepted_records) and a accepted_count variable that was set somewhere else can drift apart the moment anything between the two touches one and not the other. The records list is the evidence; a count that is not derived from it, at the moment the report is built, is a belief about the evidence rather than a reading of it.

Sort before you print, every time, for the same reason a folder survey did. A dictionary built by grouping records preserves whatever order they happened to arrive in, and that order is not the report's to decide - it is an accident of which record came first in the batch. Reporting the totals in a fixed, sorted order is what makes two reports over related runs comparable: the line for a given region is on the same line number in both, and a difference between them is a real difference in the numbers, not a difference in how a dictionary iterated.

Join a sorted breakdown into one line rather than printing one line per item. ", ".join(f"{name}={total}" for name in sorted(totals)) puts the whole ordering decision into a single string a test - or a person - can compare directly against what it should be. Separate print statements let the lines land in whatever order the loop produced them, and nothing then confirms they were in the right order rather than merely all present.

Accepted survey responses from one run, aggregated and reported:

RUN = {
    "source": "weekly-survey.json",
    "run_at": "2026-09-07T08:00:00Z",
    "read_count": 6,
    "quarantined_count": 1,
    "responses": [
        {"id": "p1", "team": "sales", "score": 4},
        {"id": "p2", "team": "support", "score": 5},
        {"id": "p3", "team": "sales", "score": 3},
        {"id": "p4", "team": "support", "score": 4},
        {"id": "p5", "team": "engineering", "score": 5},
    ],
}


def aggregate_by_team(responses):
    totals = {}
    for response in responses:
        totals[response["team"]] = totals.get(response["team"], 0) + response["score"]
    return totals


def build_report(run):
    lines = [f"source: {run['source']}", f"run at: {run['run_at']}"]
    accepted = run["responses"]
    lines.append(f"read: {run['read_count']}")
    lines.append(f"accepted: {len(accepted)}")
    lines.append(f"quarantined: {run['quarantined_count']}")
    reconciled = run["read_count"] == len(accepted) + run["quarantined_count"]
    lines.append(f"reconciled: {reconciled}")
    totals = aggregate_by_team(accepted)
    breakdown = ", ".join(f"{name}={totals[name]}" for name in sorted(totals))
    lines.append(f"teams: {breakdown}")
    return lines


for line in build_report(RUN):
    print(line)

aggregate_by_team builds its dictionary in whatever order teams first appear in responses - sales first here - which is exactly why build_report reads it back out through sorted(totals) rather than iterating the dictionary directly.

reconciled is computed from run["read_count"], len(accepted), and run["quarantined_count"] at the moment the report is built, not copied from anywhere else - if any one of those three numbers were wrong, this line would be the thing that says so.

Predict every line.

source: weekly-survey.json
run at: 2026-09-07T08:00:00Z
read: 6
accepted: 5
quarantined: 1
reconciled: True
teams: engineering=5, sales=7, support=9

Replace for name in sorted(totals) with for name in totals, reading the dictionary in whatever order it was built rather than sorting it.

teams: sales=7, support=9, engineering=5

An assistant was asked to "write a summary report for this batch". It produced this.

def summarise(run, accepted_count):
    print(f"Report for {run['source']}")
    print(f"Processed {accepted_count} of {run['read_count']} records successfully")
    totals = {}
    for record in run["responses"]:
        totals[record["team"]] = totals.get(record["team"], 0) + record["score"]
    for name, total in totals.items():
        print(f"{name}: {total}")

def build_report(run):
    """Build the report as a list of lines. Every number is derived from run."""
    accepted = run["responses"]
    lines = [f"source: {run['source']}", f"run at: {run['run_at']}"]
    lines.append(f"read: {run['read_count']}")
    lines.append(f"accepted: {len(accepted)}")
    lines.append(f"quarantined: {run['quarantined_count']}")
    lines.append(f"reconciled: {run['read_count'] == len(accepted) + run['quarantined_count']}")
    totals = aggregate_by_team(accepted)
    lines.append("teams: " + ", ".join(f"{n}={totals[n]}" for n in sorted(totals)))
    return lines

Two runs are supplied as JSON, in RUN_A_JSON and RUN_B_JSON, each carrying a source, a timestamp, read_count, quarantined_count, and a list of accepted records. Write aggregate_by_region and build_report: aggregate, reconcile from the run's own numbers, and report regions in sorted order on one joined line.

Loading this exercise…

Optional, and the transfer task for this lesson: decide what the report should say about a region with no accepted records at all.

aggregate_by_region only ever reports a region that appears in at least one accepted record. Extend the report so it also states which regions from a supplied list of expected regions - say, every region the business operates in - are missing from this run's accepted records entirely, and decide what that should mean: is a region with zero accepted shipments today a fact worth a line in the report, or noise?

Sign in to track your progress on this exercise.

1. Name the two pieces of run metadata a report opens with, and what a reader loses without them.
2. Why should accepted in a report be len(accepted_records) rather than a count passed in separately?
3. Why does a breakdown get joined into one line instead of printed one line per item?
4. A report prints reconciled: True on every run it has ever produced, including runs a person later found had dropped records. What is the most likely cause?

Sign in to track your progress on this exercise.

A report is a list of lines built as data before anything prints: what was read, when, and from where; the counts read, accepted, and quarantined; a reconciliation line computed from those three numbers rather than assumed; and an aggregate breakdown sorted before it is joined into a single line, so two reports over related runs can be compared line by line. A report that never checks its own arithmetic is a summary of what the code believed happened, not of what happened. That closes this module: records arrive, get coerced or rejected, get validated or quarantined, and end up in a report whose numbers a reader can trust because the report checked them itself. The next module turns to data a job cannot read from a file at all - a service on the other end of a request, which will not always answer, and will not always answer quickly.