argparse Part 2: Subcommands & Defaults

By the end of this lesson you can:

• Create subcommands with parser.add_subparsers().
• Give each subcommand its own arguments.
• Wire each subcommand to a handler function with set_defaults(func=...).
• Structure a real multi-command tool that's easy to extend.

Look at the shape of the tools you use every day:

git    add file.py      git    commit -m "msg"     git    push
pip    install requests pip    list               pip    uninstall x
docker build .          docker run image          docker ps

Each is one program with several subcommands, and each subcommand takes different arguments. git add wants files; git commit wants a message.

The structure

import argparse

parser = argparse.ArgumentParser(description="A todo tool.")
sub = parser.add_subparsers(dest="command", required=True)

# verb: add
p_add = sub.add_parser("add", help="add a task")
p_add.add_argument("task")

# verb: list
p_list = sub.add_parser("list", help="show all tasks")

# verb: remove
p_remove = sub.add_parser("remove", help="delete a task")
p_remove.add_argument("number", type=int)

args = parser.parse_args()
print(args)

Each sub.add_parser("verb") returns a fresh parser you configure independently.

$ python todo.py add "buy milk"
Namespace(command='add', task='buy milk')

$ python todo.py remove 2
Namespace(command='remove', number=2)

$ python todo.py list
Namespace(command='list')

dest="command" stores which verb was chosen; required=True means the user must pick one.

The dispatch problem

You could branch on args.command with a big if/elif chain — but that gets messy as tools grow. The clean pattern attaches a handler function to each subparser:

def cmd_add(args):
    print(f"Adding: {args.task}")

def cmd_list(args):
    print("Listing all tasks…")

def cmd_remove(args):
    print(f"Removing task #{args.number}")

p_add.set_defaults(func=cmd_add)
p_list.set_defaults(func=cmd_list)
p_remove.set_defaults(func=cmd_remove)

args = parser.parse_args()
args.func(args)          # call the handler the chosen verb set

set_defaults(func=...) stores the right function on args. After parsing, args.func(args) runs exactly the handler for the verb the user picked. Adding a new command is now three lines: a subparser, a handler, and a set_defaults — no editing a giant if.

Per-subcommand options

Each subparser is a full parser, so it gets its own flags too:

p_list = sub.add_parser("list")
p_list.add_argument("--done", action="store_true",
                    help="only show completed tasks")

Now python todo.py list --done works, but python todo.py add --done correctly errors — --done belongs only to list.

Let's make it real — tasks stored in a JSON file, so they survive between runs.

import argparse, json
from pathlib import Path

STORE = Path("tasks.json")

def load():
    return json.loads(STORE.read_text()) if STORE.exists() else []

def save(tasks):
    STORE.write_text(json.dumps(tasks, indent=2))

def cmd_add(args):
    tasks = load()
    tasks.append(args.task)
    save(tasks)
    print(f"Added: {args.task}")

def cmd_list(args):
    tasks = load()
    if not tasks:
        print("No tasks yet.")
    for i, t in enumerate(tasks, start=1):
        print(f"{i}. {t}")

def cmd_remove(args):
    tasks = load()
    if 1 <= args.number <= len(tasks):
        removed = tasks.pop(args.number - 1)
        save(tasks)
        print(f"Removed: {removed}")
    else:
        print(f"No task #{args.number}")

parser = argparse.ArgumentParser(description="A tiny todo manager.")
sub = parser.add_subparsers(dest="command", required=True)

p_add = sub.add_parser("add", help="add a task")
p_add.add_argument("task")
p_add.set_defaults(func=cmd_add)

p_list = sub.add_parser("list", help="show tasks")
p_list.set_defaults(func=cmd_list)

p_remove = sub.add_parser("remove", help="delete a task by number")
p_remove.add_argument("number", type=int)
p_remove.set_defaults(func=cmd_remove)

args = parser.parse_args()
args.func(args)

$ python todo.py add "buy milk"
Added: buy milk
$ python todo.py add "call dentist"
Added: call dentist
$ python todo.py list
1. buy milk
2. call dentist
$ python todo.py remove 1
Removed: buy milk

Read the code

The whole tool is data plus three small handlers — and the dispatch trick keeps each verb self-contained. Want a done command next? Add a subparser, a handler, a set_defaults. The structure scales: this is exactly how professional CLIs are organised.

Subcommands turn one script into a suite of verbs. Call parser.add_subparsers(dest=..., required=True), then sub.add_parser("verb") for each command — each is a full parser with its own arguments. Attach a handler with p.set_defaults(func=...) and run args.func(args) after parsing to dispatch. Adding a new command stays a tidy three-line change, which is why every serious CLI is built this way.