The Dry Run That Tells You What Would Happen

By the end of this lesson you can split an automation into a step that decides what to change and a step that carries it out, express the intended changes as data you can print and count, and write an apply step whose dry-run mode provably changes nothing.

Every automation in this course changes something eventually. The question is whether you find out what it intends to change before or after it does it.

A dry run is the answer, and it is also the most commonly faked feature in automation. A dry run that logs "would rename 412 files" while having already created the destination folder is not a dry run. A dry run that reports what it would do based on a second code path, written separately from the real one, is worse: it tells you about a program that is not the one that will run.

There is one design that avoids both, and it is the subject of this lesson. Decide first, and record the decision as data. Then hand that data to a step that either describes it or performs it. The dry run and the real run consider exactly the same list, because it is the same list.

The habit pays off well beyond safety. A plan you can print is a plan you can review, count, diff against yesterday's, hand to somebody for approval, and save as evidence of what a run intended. None of that is available when the decision only ever exists as control flow inside a loop that is already writing files.

Plan, then apply.

A plan function reads the current state and returns a list of intended changes. It writes nothing. An apply function takes that list and either performs it or describes it. It decides nothing.

An intended change is a small dictionary with an action and whatever that action needs:

{"action": "set", "key": "b", "value": 20}
{"action": "delete", "key": "a"}
{"action": "move", "source": "inbox/x.csv", "target": "archive/2026-09/x.csv"}

Data, not a function call. That is what makes it printable, countable, comparable between runs, and reviewable by somebody who does not read Python.

The four-point test for a real dry run. A dry run passes only if all four hold:

1. It performs no action from the plan. Nothing is written, moved, deleted, or sent.
2. It creates nothing incidentally. No destination folder, no lock file, no log file, no empty output. This is the point most implementations fail: the setup happens before the branch that checks the flag.
3. It reports every intended change, individually. A count is not a report. "Would change 412 files" cannot be reviewed; 412 lines can be read, sampled, and searched.
4. It is the same code path. The dry run and the real run consume the identical plan and differ only at the moment of performing an action.

Default to the dry run. The safe mode is the one you get by accident. A script whose default is to change things will eventually be run by somebody who did not read the arguments — often you, in a hurry. The flag that changes things should have to be typed: --apply, never --dry-run as an opt-in.

Return what happened. apply should report the number of changes it actually made, which is zero in a dry run by definition. That number is what the run record in Module 5 stores, and comparing "planned" against "made" is how you detect a run that stopped halfway.

One caution about scope. A dry run tells you what the job intends given the state it just read. It is not a promise about what will happen when the real run executes an hour later against state that has changed since. Planning and applying in the same run narrows that gap but does not remove concurrent changes. Recheck important preconditions at the effect boundary when state can change.

A tiny store, a plan that decides, and an apply that performs or describes:

STOCK = {"blue-pen": 4, "red-pen": 0, "notebook": 11}
REORDER_LEVEL = 5


def plan(stock, level):
    """Decide what to reorder. Reads state, writes nothing, returns intentions."""
    intentions = []
    for item, count in sorted(stock.items()):
        if count < level:
            intentions.append({"action": "order", "item": item, "quantity": level - count})
    return intentions


def apply(intentions, stock, dry_run=True):
    """Perform the plan, or describe it. Decides nothing."""
    made = 0
    for intention in intentions:
        line = f"order {intention['quantity']} x {intention['item']}"
        if dry_run:
            print("would", line)
            continue
        stock[intention["item"]] += intention["quantity"]
        made += 1
    return made


intentions = plan(STOCK, REORDER_LEVEL)
print("planned:", len(intentions))
print("made in dry run:", apply(intentions, STOCK, dry_run=True))
print("stock unchanged:", STOCK["red-pen"])
print("made for real:", apply(intentions, STOCK, dry_run=False))
print("stock now:", STOCK["red-pen"])

plan sorts the items, so two runs over the same stock produce the plan in the same order and a diff between them shows real changes rather than dictionary ordering.

apply builds the description string once and uses it in both branches. When the wording of a dry-run line is produced by different code from the action it describes, the two drift, and the drift is invisible until the day the description is wrong.

made counts only actions actually performed, which is why it returns zero from the dry run without any special case: the continue skips the increment along with the change.

Predict all seven printed lines, including the two would lines.

planned: 2
would order 1 x blue-pen
would order 5 x red-pen
made in dry run: 0
stock unchanged: 0
made for real: 2
stock now: 5

Move the made += 1 line above the if dry_run: block, so it counts every intention rather than every action.

An assistant was asked to "add a dry-run option to the archiver". It produced this.

def archive(records, destination, dry_run=False):
    destination.mkdir(parents=True, exist_ok=True)
    log = open(destination / "archive.log", "a", encoding="utf-8")
    moved = 0
    for record in records:
        if dry_run:
            log.write(f"DRY RUN: would archive {record['id']}\n")
        else:
            (destination / f"{record['id']}.json").write_text(record["body"], encoding="utf-8")
        moved += 1
    log.close()
    print(f"archived {moved} records")
    return moved

def archive(records, destination, apply_changes=False):
    intentions = [{"id": r["id"], "body": r["body"]} for r in records]
    if apply_changes and intentions:
        destination.mkdir(parents=True, exist_ok=True)
    moved = 0
    for intention in intentions:
        line = f"archive {intention['id']}"
        if not apply_changes:
            print("would", line)
            continue
        (destination / f"{intention['id']}.json").write_text(intention["body"], encoding="utf-8")
        moved += 1
    return moved

A store and a plan of intended changes are supplied. Write apply, which performs the plan or describes it. In dry-run mode it must print one would ... line per intention using the supplied describe helper, change nothing, and return 0. In apply mode, a set to the same value or a delete of an absent key is a no-op and does not increase made.

Loading this exercise…

Optional, and the transfer task for this lesson: take the dry run one step further, into something you could hand to somebody else.

Extend the exercise so apply returns the number planned, the number of state changes made, and intentions it could not carry out. Add an explicit precondition to a set intention, such as an expected old value. Change the store before apply so that precondition fails, and report the conflict. A plain set of a new key is valid in the supplied fixture; deleting an already-absent key is already satisfied and should not increment made.

Sign in to track your progress on this exercise.

1. What does plan return, and why is it data rather than a series of calls?
2. Name the four conditions a genuine dry run satisfies.
3. Why should the flag be --apply rather than --dry-run?
4. A dry run prints only would archive 412 records and reports archived 412 records. Which dry-run reporting rule fails, and what is wrong with the count?

Sign in to track your progress on this exercise.

Decide first and record the decision as data; then hand that data to a step that either performs it or describes it. A genuine dry run performs nothing, creates nothing incidentally, reports every intended change individually, and shares its code path with the real run. Default to it, and count changes where they happen rather than where they are decided. The next module takes this pattern to the place it is needed most: files, where a rename is instant and a mistake is not always reversible.