Report the Page, and Test What You Built

Your tool can now find a page from three different places. What it cannot do yet is say anything about it. This lesson turns a validated page into the text a person actually reads.

The work splits in two, and keeping the halves apart is most of the lesson.

Counting is not printing

summarize_page(page_document) answers questions about the data. How many items? What do their values add up to? What does that look like broken down by category?

It returns data, not text:

{
    "item_count": 3,
    "value_total": 60,
    "categories": [
        {"category": "color", "item_count": 2, "value_total": 30},
        {"category": "shape", "item_count": 1, "value_total": 30},
    ],
}

render_report(...) takes a page and produces the finished string. It does no arithmetic of its own; it asks summarize_page and lays out the answer.

Why bother separating them? Because they change for different reasons. You will want to adjust the wording of the report far more often than you will want to change what “total” means, and a function that does both makes every wording tweak a chance to break the arithmetic. It also means you can test the counting with plain dictionary comparisons, instead of picking numbers out of a paragraph.

Sort the categories, always

Categories come out of a dictionary you built while walking the items, so their order reflects the order they happened to appear. Two runs over the same data in a different order produce reports that differ only in the order of their lines.

That is a bad property for something people compare. Sort by category name and the report becomes a stable thing you can diff against yesterday’s.

The items themselves keep the order the API sent, because that order is data. The categories are your own grouping, so their order is yours to decide.

Make the names unambiguous

A category is text from a service. Text can contain a comma, a quote, or a newline, and any of those turn a tidy line into a confusing one.

name = json.dumps(category["category"], ensure_ascii=False)

json.dumps on a string returns that string quoted and escaped: "color" stays readable, and a name containing a newline comes out as a single unambiguous token instead of silently splitting your report across two lines. ensure_ascii=False keeps genuine non-ASCII characters legible rather than turning café into caf\u00e9.

This costs one function call and removes a whole family of confusing bugs.

The exact shape

Practice API report
source: network
fetched_at: 1754000000
page: 1
page_size: 3
dataset_total: 5
item_count: 3
value_total: 60
categories:
- "color": 2 item(s), 30 value
- "shape": 1 item(s), 30 value

source is one of network, fresh-cache, stale-cache, or offline, so the report says where its data came from. That matters: a reader deserves to know whether they are looking at a live answer or an hour-old one.

fetched_at is the timestamp for every source except offline, which has none and prints none. An offline report has no fetch time, and inventing one would be a lie in a file people keep.

One trailing newline at the end, as always.

Keep it pure

render_report takes values and returns a string. It does not open files, read the clock, or make requests.

That is what lets Chapter 13’s CLI render the whole report before it opens the destination file, which in turn is what makes a failure during rendering leave your previous report intact. The same “do the work that can fail before the step that destroys something” rule from lesson 1, arriving now as a consequence of a decision you made here.

Your turn

Two pieces of work, and they belong together.

First, add summarize_page(page_document) and render_report(page_document, *, source, fetched_at) to practice_report.py, following the shape above. Both use the report-specific page validation and leave the input unchanged. Pass source and fetched_at by name when calling the renderer.

The renderer rejects an unknown source with ValueError. For source="offline", require fetched_at=None and render the word none. For every other source, require a genuine non-negative integer timestamp; reject booleans and other invalid values with ValueError. An empty page has zero items, zero total value, and an empty category list, so its report ends just after categories: and the final newline.

Then write tests/test_practice_report.py, covering not just the report but everything the chapter has built so far. This is the module the capstone will lean on, so it is worth more than a token pass:

• cache validation: a good document round-trips; a boolean fetched_at is refused; a cache for page 2 is refused for a request for page 1.

• freshness: age equal to max_age is fresh, one second more is stale, a future timestamp raises.

• source selection: a fresh cache makes no request; a missing cache fetches once; --refresh does not fall back; a TypeError from the fetch is not swallowed.

• the report: categories sorted, an empty page handled, offline printing fetched_at: none, exactly one trailing newline.

Use the fake-session pattern from Chapter 11 for anything that would otherwise reach the network, inject now_epoch everywhere rather than reading the clock, and keep every file your tests create under tmp_path.

Aim for tests that would notice a realistic mistake. The question to ask about each one is not “does this pass?” but “what would have to break for this to fail?” If you cannot answer that, the test is decoration.