Organize a Small Read–Compute–Write Program

A small program becomes easier to inspect when each file has one clear role. The measurement report now has enough parts to justify a simple layout: saved input, reusable calculations, one runner, and generated output.

Use Only the Structure the Program Needs

This layout is sufficient:

measurement_report/
  data/
    measurements.txt
  reports/
    summary.txt
  measurement_tools.py
  run_report.py

The folders and files answer four practical questions:

The structure matters because the roles differ. It is not a rule that every Python program needs four files. Add a file or folder when it owns a real responsibility, not merely to make a small program look larger.

Keep Reusable Work Independent of Paths

measurement_tools.py accepts ordinary strings and values. It does not open a particular file:

The functions state their inputs through parameters and return their results. parse_measurements does not assume a filename. build_report produces text but does not decide where to save it. This separation lets us inspect each stage with a small direct call.

The mean function keeps the Chapter 4 contract: no available readings produce None. The complete runner will have accepted readings, so formatting the numerical mean is valid there. A more general report function would need to state how it formats the legitimate None result.

Let the Runner Own the Workflow

run_report.py knows the project paths and the order of work:

Read the runner from top to bottom:

1. name the input and output locations;
2. reject missing supplied input rather than creating it;
3. read and parse the UTF-8 text;
4. compute the report through reusable functions;
5. create the generated-output directory;
6. write and read back the report;
7. verify the exact saved text.

This is the chapter's complete path. The runner owns sequence and locations; the imported module owns reusable transformations.

Run Again and Repair from Evidence

Run the unchanged program a second time. Because the report uses write mode, the second run replaces summary.txt with the same derived text instead of adding a duplicate report. The exact read-back assertion should pass again.

Now suppose the runner contains a path typo:

input_path = Path("data") / "measurement.txt"

The supplied file is named measurements.txt, with a final s. The useful evidence is not merely “the file is missing.” Inspect the location the runner actually requested:

The resolved path and False result identify the mismatch. Repair the filename, rerun the complete workflow, and require the read-back assertion to pass. Do not create an empty measurement.txt; that would hide the missing-input defect and produce a different experiment.

Preserve the Same Roles in Browser Python

Browser Python uses a temporary in-memory file system, but the program roles do not change. A complete browser example may create its own supplied fixture at the beginning because a fresh runtime starts without project files. That setup is separate from the workflow being practised.

The following exercise keeps the program in one editor so it can run here. The commented setup creates the input fixture. The code below it must read that input, write a derived report elsewhere, and verify the saved result.