Python: from first script to a useful automation

Learn in your browser · Chapter 01 of 06

Install Python, try one line, then run a saved script.

A script is a plain text file of instructions. Python, the interpreter, carries them out from top to bottom. Automation means writing them once and running them whenever you like.

Installing. Get Python from python.org and follow its current instructions, because they change. On Windows, the Python documentation recommends the Python install manager and calls the older full installer deprecated. Recent macOS versions include a python3 command meant for Apple's own tools, so you can install a current version from python.org alongside it. Most Linux systems already have Python or offer it as a package.

Choose a supported version: python.org lists them, and at the time of writing supports each for five years. This workbook was tested on Python 3.12.10 on Windows 11 and uses only what comes with Python.

Open a terminal (Terminal on macOS and Linux, PowerShell on Windows) and type the first line. The second is the reply, and yours may differ.

python --version
Python 3.12.10

On macOS and Linux the command is python3, so type that wherever this workbook says python. On Windows, py also works. The command alone opens the interactive prompt (>>>), where each line runs at once. Leave with quit().

To keep your work, write a script. Save this as hello.py in a folder called python-first, using a plain text editor (check the name ends .py, not .py.txt). Open a terminal there, or use cd python-first, and run it. The # line is a comment that Python ignores.

# hello.py: my first script
print("Hello from Python")
print(6 * 7)

python hello.py
Hello from Python
42

Learn in your browser · Chapter 02 of 06

Programs remember values, make decisions and repeat work. Learn these three and you can read most short scripts.

A variable is a name attached to a value, as in price = 2.5. Every value has a type that decides what you can do with it.

Scroll sideways to see every column.

3 is a number but "3" is text, and Python will not add the two: it stops with a TypeError rather than guess.

Decisions use if, elif and else; loops use for. Indentation shows what belongs inside, so keep it consistent. An f-string such as f"Total: {total:.2f}" puts a value in text, and .2f means two decimal places.

prices = {"tea": 2.5, "coffee": 3.0, "cake": 4.25}
order = ["tea", "cake", "cake", "juice"]

total = 0.0
for item in order:
    if item in prices:
        total = total + prices[item]
    else:
        print(f"No price for {item}, skipping it")

print(f"Total: {total:.2f}")

No price for juice, skipping it
Total: 11.00

Read it aloud: for each item, if we have a price add it, otherwise say so.

Learn in your browser · Chapter 03 of 06

Functions organise your work, and files and paths are how scripts touch the real world.

A function starts with def, takes inputs (parameters) and hands back a result with return. The triple-quoted docstring says what it is for. Small, well-named functions are easy to read, reuse and test.

from pathlib import Path

GROUPS = {".jpg": "Images", ".png": "Images", ".pdf": "Documents", ".txt": "Documents", ".csv": "Data"}


def group_for(filename):
    """Return the group for a file name, judged by its extension."""
    return GROUPS.get(Path(filename).suffix.lower(), "Other")


print(group_for("Holiday.JPG"))
print(group_for("readme"))

Images
Other

.lower() makes Holiday.JPG match .jpg. .get(key, default) falls back to Other for unknown types.

Paths. pathlib.Path treats a path as an object: Path("practice") / "notes.txt" joins pieces with your system's separator. Useful tools:

• path.name and path.suffix give the file name and extension.
• path.exists() and path.is_file() ask questions and change nothing.
• folder.iterdir() lists a folder in arbitrary order, says the documentation, so use sorted(...).
• path.read_text(encoding="utf-8") reads a file. path.write_text(...) writes one, replacing any existing file.

The dry-run habit. A script that changes files should do nothing until you ask. sys.argv lists the words on the command line, starting with the script name, so "--create" in sys.argv is true only if you typed the flag. Save this as make_practice.py.

import sys
from pathlib import Path

NAMES = ["holiday.jpg", "budget.CSV", "notes.txt", "scan.pdf", "readme", "logo.png"]
create = "--create" in sys.argv
folder = Path("practice")

if create:
    folder.mkdir()
for name in NAMES:
    print("Creating" if create else "Would create", name)
    if create:
        (folder / name).write_text("practice file\n", encoding="utf-8")

Run it plain, read the plan, then add --create. If practice exists, mkdir stops with an error rather than mixing files in.

Learn in your browser · Chapter 04 of 06

Real data is messy, so learn to read files and to fail well.

Open files inside a with block, which closes the file even if something goes wrong. Always pass encoding="utf-8", because up to Python 3.14 the default depends on your platform. The mode sets the risk.

Scroll sideways to see every column.

CSV (comma-separated values) is the plain text format that spreadsheets export. csv.DictReader gives each row as a dictionary keyed by the header names. The documentation says to open CSV files with newline="". Save this as spending.csv, as plain text.

date,category,amount
2026-09-01,Food,12.50
2026-09-01,Travel,40.00
2026-09-02,Food,7.25
2026-09-03,Travel,abc

The last row is deliberately bad. This script totals each category and counts the rows it skips.

import csv


def total_by_category(path):
    totals = {}
    skipped = 0
    with open(path, newline="", encoding="utf-8") as f:
        for row in csv.DictReader(f):
            try:
                amount = float(row["amount"])
            except ValueError:
                skipped += 1
                continue
            category = row["category"]
            totals[category] = totals.get(category, 0) + amount
    return totals, skipped


totals, skipped = total_by_category("spending.csv")
for category, amount in sorted(totals.items()):
    print(f"{category}: {amount:.2f}")
print(f"Skipped {skipped} unreadable row(s)")

Food: 19.75
Travel: 40.00
Skipped 1 unreadable row(s)

Without the try, that row would stop the script with a traceback. Read it from the bottom: the last line names the problem, here ValueError: could not convert string to float: 'abc'. Catch the specific error you expect, never a bare except:.

Learn in your browser · Chapter 05 of 06

Combine everything into one tool that sorts a folder's files by type and reports what it did.

Write the rules before the code.

• Plan first. One function works out every move and changes nothing.
• Dry run by default. Nothing moves without --apply.
• Never delete or overwrite. If a name is taken, skip the file and say so.
• Keep a log. Each move goes into a CSV file, so you can undo it by hand.

Save this as tidy.py, outside the folder you will tidy.

"""tidy.py: sort the files in ONE folder into sub-folders by type. A dry run by default."""
import argparse
import csv
from datetime import datetime
from pathlib import Path

GROUPS = {".jpg": "Images", ".png": "Images", ".pdf": "Documents", ".txt": "Documents", ".csv": "Data"}


def group_for(filename):
    return GROUPS.get(Path(filename).suffix.lower(), "Other")


def plan_moves(folder):
    """List (source, destination) pairs. Changes nothing."""
    moves = []
    for item in sorted(folder.iterdir()):  # no fixed order, so sort
        if item.is_file() and not item.name.startswith((".", "tidy-log")):
            moves.append((item, folder / group_for(item.name) / item.name))
    return moves


def apply_moves(moves):
    rows = []
    for source, destination in moves:
        if destination.exists():
            result = "skipped: name already exists"
        else:
            try:
                destination.parent.mkdir(exist_ok=True)
                source.rename(destination)
                result = "moved"
            except OSError as error:
                result = f"failed: {error}"
        rows.append({"file": source.name, "to": destination.parent.name, "result": result})
    return rows


def write_log(folder, rows):
    name = f"tidy-log-{datetime.now():%Y%m%d-%H%M%S-%f}.csv"
    with open(folder / name, "x", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=["file", "to", "result"])
        writer.writeheader()
        writer.writerows(rows)


def main(argv=None):
    parser = argparse.ArgumentParser()
    parser.add_argument("folder", type=Path)
    parser.add_argument("--apply", action="store_true", help="really move the files")
    args = parser.parse_args(argv)
    if not args.folder.is_dir():
        print("Not a folder:", args.folder)
        return 1

    moves = plan_moves(args.folder)
    for source, destination in moves:
        print(f"  {source.name}  ->  {destination.parent.name}")
    if not args.apply:
        print(f"Dry run: {len(moves)} file(s) would move. Add --apply to do it.")
    elif moves:
        rows = apply_moves(moves)
        write_log(args.folder, rows)
        moved = sum(1 for row in rows if row["result"] == "moved")
        print(f"Moved {moved} of {len(rows)} file(s). A log was written in the folder.")
    else:
        print("Nothing to move.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

plan_moves only looks. apply_moves checks destination.exists() first, because the documentation says rename silently replaces an existing file on Unix (macOS and Linux) but raises an error on Windows. write_log opens with "x", so it cannot overwrite a log. main uses argparse (standard library) to read your options and add --help.

Do the dry run on the practice folder first.

python tidy.py practice
  budget.CSV  ->  Data
  holiday.jpg  ->  Images
  logo.png  ->  Images
  notes.txt  ->  Documents
  readme  ->  Other
  scan.pdf  ->  Documents
Dry run: 6 file(s) would move. Add --apply to do it.

Nothing moved. When the plan looks right, add --apply. It ends Moved 6 of 6 file(s). A log was written in the folder. The files now sit in four sub-folders, and a tidy-log CSV records each move. To undo one, move it back by hand.

Learn in your browser · Chapter 06 of 06

A tool you have not tested is a tool you are hoping about. Add a first test, then learn to read code you did not write.

A unit test is a small program that checks one piece of code and reports pass or fail. Python includes unittest. Put tests in a file starting test, subclass unittest.TestCase and start each method name with test. These tests use tempfile.TemporaryDirectory(), a scratch folder that Python removes afterwards, so they never touch your real files. Save this as test_tidy.py beside tidy.py and run python -m unittest there.

import tempfile
import unittest
from pathlib import Path

import tidy


class TidyTests(unittest.TestCase):
    def test_group_for(self):
        self.assertEqual(tidy.group_for("Holiday.JPG"), "Images")
        self.assertEqual(tidy.group_for("readme"), "Other")

    def test_never_overwrites(self):
        with tempfile.TemporaryDirectory() as tmp:
            folder = Path(tmp)
            (folder / "Documents").mkdir()
            (folder / "Documents" / "a.txt").write_text("old", encoding="utf-8")
            (folder / "a.txt").write_text("new", encoding="utf-8")
            rows = tidy.apply_moves(tidy.plan_moves(folder))
            self.assertEqual(rows[0]["result"], "skipped: name already exists")
            self.assertEqual((folder / "Documents" / "a.txt").read_text(encoding="utf-8"), "old")


if __name__ == "__main__":
    unittest.main()

..
----------------------------------------------------------------------
Ran 2 tests in 0.015s

OK

Two dots mean two passes, and the time will differ.

Reading other people's code. Read before you run: the docstring, then the import lines, the function names and the bottom of the file. Then ask:

Scroll sideways to see every column.

AI-written code. An AI assistant can explain a script line by line, add a dry run or suggest tests. But it writes plausible text, so its code can look tidy and still be wrong, use functions that do not exist or ignore your safety. Treat it as a draft from a fast stranger: read it, run it on copies and test it. Never paste passwords or other people's data into a prompt.

Here is a function of the kind you might be handed. Do not run it on real files.

def average_score(filename):
    try:
        f = open("C:\\Users\\sam\\scores.csv")
        rows = f.read().split("\n")
        total = 0
        for r in rows:
            total = total + int(r.split(",")[1])
        return total / len(rows)
    except:
        return 0


print(average_score("scores.csv"))

Know your limits. You now have the basics, not a professional engineering education. Real projects need design, version control, review and upkeep. The official Python Tutorial assumes you have programmed before, and the Python Beginner's Guide points to resources for people who have not. Keep the habits: read first, dry run first, never delete, test.