🏆Capstone project: Project: Prove the Failure Boundaries

The catalog CLI now has a useful failure shape, not merely more exception handling. Each layer keeps the evidence it owns:

• argparse rejects invalid commands before conversion and uses status 2;

• the read boundary reports expected filesystem, encoding, CSV, and schema failures with status 1;

• selection defects escape with their original traceback;

• the write boundary reports only operating-system failures with status 1;

• writer validation defects escape with their original traceback;

• success is printed only after a requested artifact was written.

Run the completed project against the seeded catalog:

python catalog.py catalog.csv selected.json --minimum-quantity 4
cat selected.json

The success contract is unchanged from Chapter 8:

Wrote 2 items to selected.json.

The JSON contains BK-101 and PN-330 in input order. Its UTF-8 text, value types, two-space indentation, and one trailing newline remain the Chapter 7 artifact contract.

Exercise one expected failure

Run the same valid command shape with a missing input:

python catalog.py missing.csv selected.json --minimum-quantity 4

stdout stays empty. stderr begins with Could not read missing.csv: and the process uses status 1. Most importantly, selected.json is not rewritten by this failed read. You can cat it again to see the earlier successful artifact.

That observation is narrower than transaction safety. A later output failure has no rollback promise because the writer still writes directly to its path. The program reports the failed output operation and makes no success claim, but a partially written destination remains possible.

Check that the same exception still means different things

The point of this chapter was that an exception’s meaning depends on where it came from, not only on its class. Here is a quick way to see whether your code actually honors that.

A ValueError raised while reading a damaged CSV row is expected input failure: it should produce a short message and status 1. A ValueError raised by your own writer’s validation means your code handed its own writer something invalid: it should escape with a traceback.

Same exception class. Opposite treatment. If both go down the same path, one of your try blocks is too wide.

Try it. Temporarily add raise ValueError("boom") at the top of write_catalog_json, run the command, and see what happens. You want a traceback, not a tidy message. Remove it afterwards.

Then do the same at the top of select_items. In this command pipeline, selection receives validated in-memory data and touches nothing outside the program, so a failure there indicates a defect and should stay loud.

Press Check my work when the success artifact and both failure boundaries behave as described.

The practical habit is one sentence: reproduce first, read the original evidence, and catch only where the failed operation has a meaning you can state honestly.