argparse Part 1: Positional & Optional Args

By the end of this lesson you can:

• Build a parser with argparse.ArgumentParser.
• Add positional arguments (required, by order) and optional ones (--flags).
• Use type=, default=, choices=, and action="store_true".
• Get a clean --help screen and friendly errors without writing them yourself.

Imagine supporting all of this with raw sys.argv:

python backup.py /data --output /backups --compress --verbose
python backup.py /data -o /backups -v
python backup.py --help

You'd need to scan the list, match flags, handle both --output and -o, deal with missing values, and write your own help text. That's dozens of fiddly, bug-prone lines.

The four-line skeleton

import argparse

parser = argparse.ArgumentParser(description="Greet someone.")
parser.add_argument("name")              # positional: required
args = parser.parse_args()               # reads sys.argv for you

print(f"Hello, {args.name}!")

Run python greet.py Aisha → Hello, Aisha!. Run it with no name and argparse prints a usage error and exits non-zero — automatically.

Positional vs. optional

• Positional — add_argument("name"). Required, identified by position, no dashes.
• Optional — add_argument("--times"). Starts with --, can be left out, has a default.

parser.add_argument("name")
parser.add_argument("--times", type=int, default=1)

args = parser.parse_args()
for _ in range(args.times):
    print(f"Hello, {args.name}!")

$ python greet.py Aisha --times 3
Hello, Aisha!
Hello, Aisha!
Hello, Aisha!

Note type=int — argparse converts "3" to 3 for you, and rejects --times abc with a clear error.

Short flags and boolean switches

parser.add_argument("-n", "--times", type=int, default=1)
parser.add_argument("-v", "--verbose", action="store_true")

args = parser.parse_args()
if args.verbose:
    print("verbose mode on")

• -n and --times are the same argument — short and long form.
• action="store_true" makes a flag that's True when present, False when absent — no value needed.

Restricting choices

parser.add_argument("--level", choices=["debug", "info", "warning"],
                    default="info")

If the user types --level shout, argparse rejects it and lists the valid options. You never write that check yourself.

The free help screen

Add help= to each argument and -h/--help works automatically:

parser.add_argument("name", help="who to greet")
parser.add_argument("-n", "--times", type=int, default=1,
                    help="how many times (default 1)")

$ python greet.py --help
usage: greet.py [-h] [-n TIMES] name

Greet someone.

positional arguments:
  name                  who to greet

options:
  -h, --help            show this help message and exit
  -n TIMES, --times TIMES
                        how many times (default 1)

Goal: python findtext.py report.txt error --ignore-case --count — search a file for a word, optionally case-insensitive, optionally just count matches.

import argparse

parser = argparse.ArgumentParser(description="Find a word in a file.")
parser.add_argument("file", help="file to search")
parser.add_argument("word", help="word to look for")
parser.add_argument("-i", "--ignore-case", action="store_true",
                    help="case-insensitive search")
parser.add_argument("-c", "--count", action="store_true",
                    help="print only the number of matches")
args = parser.parse_args()

lines = open(args.file, encoding="utf-8").read().splitlines()
needle = args.word.lower() if args.ignore_case else args.word

matches = []
for n, line in enumerate(lines, start=1):
    hay = line.lower() if args.ignore_case else line
    if needle in hay:
        matches.append((n, line))

if args.count:
    print(len(matches))
else:
    for n, line in matches:
        print(f"{n}: {line}")

$ python findtext.py log.txt ERROR --count
3

$ python findtext.py log.txt error -i
12: [error] disk almost full
47: [error] retry failed

Read the code

Notice --ignore-case becomes args.ignore_case — argparse turns dashes into underscores so it's a valid attribute name. Two boolean switches and two positionals gave us a flexible tool, with help text and validation thrown in. This is the standard shape of a real CLI: positionals for the what, flags for the how.

argparse lets you describe arguments instead of parsing them. Positionals (no dashes) are required and ordered; optionals (--flag) have defaults. Use type= to convert, default= to fall back, choices= to restrict, and action="store_true" for boolean switches. In return you get validation, friendly errors, dash-to-underscore attribute names, and a polished --help screen — none of which you have to write. Next lesson: subcommands, for git-style tools.