Thinking in automation

Every Monday, Hana in the accounts team of a small trading company downloads about forty scanned invoices. The scanner names them Invoice March 03.PDF, invoice march 04.pdf, INVOICE-March-05.pdf. She renames each one by hand to a consistent lower-case form so the archive sorts properly. It takes twenty minutes, she does it 50 times a year, and every few weeks she makes a typo that hides an invoice.

That is a perfect job for Python. But a script that renames forty files in a second can also ruin forty files in a second. This track is about automation you can trust: scripts that show you what they are about to do, never destroy data by accident, and can be run again safely.

What is worth automating?

A task is a good candidate when most of these are true:

A task that needs judgement each time ("decide which customers deserve a discount") is a poor candidate. A task with clear rules ("rename every scan to lower case with underscores") is a good one.

Before writing code, describe the automation in three parts:

• Inputs: what it reads (a folder of scans, a CSV export, a config file).
• Steps: the rules, in order (clean each name, skip names already clean, rename).
• Outputs: what changes or gets produced (renamed files, a report, a log of what happened).

Writing these down usually reveals the awkward questions early: what if two scans clean to the same name? What if the folder is empty?

Safe automation principles

These habits appear in every lesson of this track:

1. Plan, then act. First build a list of the changes the script would make. Show it. Only apply it when asked. Running with only the plan is called a dry run.
2. Never destroy originals. Prefer copying to moving, and moving to deleting. Never delete without an explicit confirmation.
3. Check before you overwrite. If the target file already exists, stop or pick a new name.
4. Record what happened. Print or log every change so you can explain (and undo) it later.
5. Make re-runs safe. Running the script twice should not do the work twice or damage anything. This property is called idempotence.
6. Fail loudly. If something unexpected turns up, stop with a clear message rather than guessing.

def clean_name(name):
    return name.strip().lower().replace(" ", "_")

scans = ["Invoice March 03.PDF", "invoice_march_04.pdf", "Receipt Fuel.png"]

plan = []
for name in scans:
    new = clean_name(name)
    if new != name:
        plan.append((name, new))

for old, new in plan:
    print(f"WOULD RENAME {old} -> {new}")
print(len(plan), "of", len(scans), "files need renaming")

Nothing on disk changed: the program only built a plan, a list of (old, new) pairs. Notice that invoice_march_04.pdf is already clean, so it is left out of the plan. That matters later: when you run the script a second time, the plan is empty and nothing happens. That is idempotence in its simplest form.

Keeping the plan as data has another benefit: you can test the planning logic with plain lists, without creating any files.

A dry-run switch

The usual shape is one function that applies a plan, with a dry_run parameter that defaults to True. Forgetting the argument should give you the safe behaviour, not the destructive one.

def apply(plan, dry_run=True):
    done = []
    for old, new in plan:
        if dry_run:
            print("WOULD RENAME", old, "->", new)
        else:
            done.append(new)
            print("RENAMED", old, "->", new)
    return done

plan = [("A.txt", "a.txt")]
print(apply(plan))
print(apply(plan, dry_run=False))

Confirm before anything destructive

Some jobs really do need to delete files, such as clearing out temporary exports. Make the script ask first, and treat anything other than an exact "yes" as no:

old_exports = ["export_0101.tmp", "export_0102.tmp", "export_0103.tmp"]

print("These files would be deleted:")
for name in old_exports:
    print("  ", name)

answer = input("Type yes to delete them: ")
if answer.strip().lower() == "yes":
    print("Deleting", len(old_exports), "files")
else:
    print("Nothing deleted.")

plan_renames(["Q1 Report.PDF", "budget.xlsx", "Team Photo.jpg"])
# [("Q1 Report.PDF", "q1_report.pdf"), ("Team Photo.jpg", "team_photo.jpg")]
plan_renames([])   # []

plan = [("Invoice March.pdf", "invoice_march.pdf")]
apply_plan(plan, "scans")
# ["WOULD RENAME Invoice March.pdf -> invoice_march.pdf"]   (nothing renamed)
apply_plan(plan, "scans", dry_run=False)
# ["RENAMED Invoice March.pdf -> invoice_march.pdf"]

scanned invoice for March

scanned receipt 01

rename_safely("docs", "draft.txt", "final.txt")   # "renamed"
rename_safely("docs", "draft.txt", "final.txt")   # "missing"  (it was already renamed)

Quarterly plan, draft 3