Capstone: a command-line app

Parsing arguments with argparse

A good receptionist reads your form, checks that the boxes make sense and sends you back if they don't. argparse does that for the words after a command. It turns them into named values, checks them, and writes --help for free. Subcommands such as add, list and done each get their own small parser:

import argparse

parser = argparse.ArgumentParser(prog="tasks", description="A to-do list for your terminal.")
sub = parser.add_subparsers(dest="command", required=True)

add = sub.add_parser("add", help="add a task")
add.add_argument("title")
add.add_argument("--priority", choices=["low", "normal", "high"], default="normal")

done = sub.add_parser("done", help="mark a task done")
done.add_argument("id", type=int)

print(parser.parse_args(["add", "Write report", "--priority", "high"]))
print(parser.parse_args(["done", "3"]))

Notice type=int: "3" arrives as text and argparse converts it, rejecting "three". That's parsing at the edge, again. When the arguments are wrong, argparse prints a usage message to stderr and raises SystemExit(2). In a real terminal that ends the program with exit code 2.

The repository

All SQL lives in one class, the records clerk from the design lesson. Everything else calls its methods and never sees a query. The ordering rule (high first) is one SQL expression:

ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'normal' THEN 1 ELSE 2 END, id

CASE turns each priority into a number for sorting, and id breaks ties so the order is always the same.

Testable from the start

Here's the most important design decision in the whole program. main takes the argument list and the repository as parameters:

def main(argv: list[str], repo: TaskRepo) -> int:
    ...

if __name__ == "__main__":
    import sys, sqlite3
    repo = TaskRepo(sqlite3.connect("tasks.db"))
    sys.exit(main(sys.argv[1:], repo))

The real program passes sys.argv and a database file. Tests pass a list such as ["add", "Buy milk"] and an in-memory database, then check what was printed and what code came back. It's the crash-test dummy again: the whole program can be tested without a terminal and without touching the disk.

import argparse, contextlib, io

def main(argv):
    parser = argparse.ArgumentParser(prog="greet")
    parser.add_argument("name")
    parser.add_argument("--shout", action="store_true")
    try:
        args = parser.parse_args(argv)
    except SystemExit as exc:
        return exc.code                    # 2 for a usage error
    text = f"Hello, {args.name}!"
    print(text.upper() if args.shout else text)
    return 0

def run(argv):
    out, err = io.StringIO(), io.StringIO()
    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
        code = main(argv)
    return code, out.getvalue().strip(), err.getvalue().strip()

print(run(["Ada"]))
print(run(["Ada", "--shout"]))
code, _, err = run([])
print(code, "|", err.splitlines()[-1])

Shipping it

To make tasks a real command, add it to pyproject.toml:

[project.scripts]
tasks = "tasks.cli:main_entry"

where main_entry() builds the real repository and calls sys.exit(main(sys.argv[1:], repo)). Then uv tool install . puts the command on your path. Add a README with install, usage and test commands, a CI workflow running ruff, mypy and the tests, and it's a project anyone can pick up.

Ideas for going further

• --json output on list, so other programs and AI agents can read the result reliably.
• Due dates, parsed with datetime.date.fromisoformat and stored as ISO text.
• tasks edit 3 --title ..., with a test written before the code (TDD).
• A service layer once there are rules beyond ordering.

Habits that separate a tool from a script

Errors go to stderr, with a non-zero exit code. If your tool prints "file not found" to stdout and exits with 0, then a script running it believes it worked, and carries on with bad data. Other programs can't read your words. They read your exit code.

Keep sys.argv at the very top. Have main(argv) take the arguments as a list, and pass them in from one place. Then a test can call main(["add", "buy milk"]) directly, with no subprocess at all. If argument reading is scattered through the program, you can't test any of it easily.

Keep SQL in one class. When queries are spread through the command-line code, changing a table means hunting through everything. With one repository class, the rest of the program never knows that SQL exists, and you could swap it for something else.

Write the requirements down first. A few lines saying what the tool must do, and what happens on bad input, will save you from discovering those questions as bugs. "What happens if the task doesn't exist?" is much cheaper to answer before you've written the code.