Command-Line Options with argparse
The words typed after a script's name arrive in sys.argv, and the argparse module turns them into a positional argument, options with defaults and flags, checks them, and writes a --help page, so one script works on any folder without editing its code.
Journeyman · Python · Updated
After this lesson you can
- Read the words typed after a script's name with sys.argv
- Give a script a positional argument, options and a flag with argparse, and read its --help page
Key takeaways
- The words typed after python script.py arrive in sys.argv, a list of strings whose first item is the script's own name.
- argparse reads those words for you. add_argument("folder") makes a positional argument, one the user must type in its place.
- An option starts with two dashes, such as --days, and gets its default when it's left out. type=int turns the typed text into a number.
- A flag such as --dry-run is True when it's typed and False when it isn't (action="store_true").
- argparse writes the --help page from your help= texts, and stops with a clear message when a required argument is missing or a word is wrong.
The tools you already use in the terminal take instructions on the same line you start them with: pip install -r requirements.txt says what to install and where the list is, and git clone takes the address to copy. Your own scripts can work the same way. Once a script takes its folder and its settings from the command line, you can run it on any folder, try it safely with a dry run, and hand it to a friend who never opens the code.
The example is a script that tidies a Downloads folder, run on a practice folder named practice-downloads.
A script that only knows one folder
Here's how a tidy-up script usually starts:
FOLDER = "practice-downloads"
DRY_RUN = True
print("Folder:", FOLDER)
print("Dry run:", DRY_RUN)
Folder: practice-downloads
Dry run: True
It works, for one folder. To tidy another one, or to stop the dry run and make the moves, you open the file and edit it. Anyone else who uses it has to find the right lines first, and an edit made in a hurry is how a script ends up pointed at the wrong folder.
sys.argv: the words after the script's name
When you start a program in the terminal, Python keeps every word you typed after python in a list named sys.argv (read "sys dot arg v", short for argument values). Each word is a command-line argument. Save this as tidy.py:
import sys
print(sys.argv)
Then run it with two words after its name:
python tidy.py practice-downloads --dry-run
['tidy.py', 'practice-downloads', '--dry-run']
The first item is the script's own name, and the rest are the words you typed, always as strings. A script could read sys.argv[1] as its folder. Then it would have to check the word is there at all, notice --dry-run wherever it comes, turn a number such as "7" into 7, and explain itself when someone types a word wrong. That's a lot of checking, and Python's argparse module does all of it for you.
argparse: say what the script takes
With argparse, you describe what the script expects, and it reads sys.argv for you:
import argparse
parser = argparse.ArgumentParser(description="Sort a downloads folder into folders by file type.")
parser.add_argument("folder", help="the folder to sort")
parser.add_argument("--to", default="Sorted", help="the folder to sort into (default: Sorted)")
parser.add_argument("--dry-run", action="store_true", help="show what would move, and move nothing")
args = parser.parse_args()
print("Folder:", args.folder)
print("Sort into:", args.to)
print("Dry run:", args.dry_run)
Each add_argument line adds one thing the script takes:
"folder"has no dashes, so it's a positional argument: the user must type it, and its place in the line says what it is."--to"starts with two dashes, so it's an option: the user may type it with a value after it, anddefault="Sorted"is what it gets when they don't."--dry-run"withaction="store_true"is a flag: an option with no value. It'sTruewhen it's typed andFalsewhen it isn't.
parse_args() reads the words and hands back args, with one attribute for each argument. A dash in a name becomes an underscore, because Python names can't hold dashes: --dry-run is args.dry_run. Two runs:
python tidy.py practice-downloads --dry-run
python tidy.py practice-downloads --to Tidy
Folder: practice-downloads
Sort into: Sorted
Dry run: True
Folder: practice-downloads
Sort into: Tidy
Dry run: False
Numbers, and trying a parser out
Every word typed in the terminal is text. type=int tells argparse to turn an option's value into a whole number, and to refuse one that isn't. You can also hand parse_args() a list of words instead of letting it read the terminal, which is handy for trying a parser out, and for tests:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("folder")
parser.add_argument("--days", type=int, default=30)
args = parser.parse_args(["practice-downloads", "--days", "7"])
print(args.folder, args.days, args.days + 1)
args = parser.parse_args(["practice-downloads"])
print(args.days)
practice-downloads 7 8
30
args.days + 1 is 8, so days is a number, not the text "7". Left out, it gets its default, 30.
--help comes free, and so do the error messages
Every argparse script answers --help (or -h) with a page built from your help= texts:
python tidy.py --help
usage: tidy.py [-h] [--to TO] [--dry-run] folder
Sort a downloads folder into folders by file type.
positional arguments:
folder the folder to sort
options:
-h, --help show this help message and exit
--to TO the folder to sort into (default: Sorted)
--dry-run show what would move, and move nothing
The usage line reads like a sentence: square brackets mark what you may leave out, and folder, outside any brackets, is required. Leave it out, or mistype an option, and the script stops before it touches a file, with a message that says what's wrong:
python tidy.py
python tidy.py practice-downloads --dryrun
usage: tidy.py [-h] [--to TO] [--dry-run] folder
tidy.py: error: the following arguments are required: folder
usage: tidy.py [-h] [--to TO] [--dry-run] folder
tidy.py: error: unrecognized arguments: --dryrun
That second stop matters for a script that moves files: a typo in --dry-run can't quietly turn into a real run.
Do it: give the receipt backup its options
A script backs up the receipts in a folder. Its user types the folder, may say how many days back to look, and may ask for a dry run.
Your job: finish the function make_parser() so the parser it returns takes:
folder: a positional argument, the folder the receipts are in. The starter has it already.--days: an option holding a whole number (anint),30when it's left out.--dry-run: a flag,Truewhen it's typed andFalsewhen it isn't.
Leaving out the folder is an error: parse_args stops with SystemExit, as the starter's parser already does.
Worked through: make_parser().parse_args(["practice-downloads", "--days", "7"]) gives folder "practice-downloads", days the number 7 and dry_run False, because --dry-run wasn't typed.
Practiced live on the lesson page: write the Python right there and check it.
Check yourself
2 questions to try on the lesson page.
So what
A script that takes its folder and settings from the command line, with a dry run and a --help page, is a tool: you run it on any folder, and so can someone who has never read its code.