Overview
This tutorial uses the built-in Pyton module argparse
.
Sub-Commands
Complex command-line programs can be simplified with the concept of sub-commands
. Sub-commands are named commands as the first argument passed into a program, where each sub-command has it’s own unique set of required and optional arguments.
A well-known program with sub-commands is git
. The git
command-line program has various sub-commands such as:
git clone
git add
git commit
Each one of these sub-commands has it’s own required and optional arguments.
If you find yourself starting to add options that are only applicable when certain other arguments are present, then it might be time to look into sub-commands.
argparse
has sub-command support through the use of add_subparsers()
. The following working example shows a Python program which has two sub-commands, add
and print
.
Passing in dest='command'
to add_subparsers()
allows us to query the sub-command invoked through args.command
.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
#!/usr/bin/env python3
import argparse
def main():
parser = argparse.ArgumentParser(description='Example argument parser with sub-commands.')
<span style="color:#0080ff;font-style:italic"># Setting dest='command' means we can later check args.command to see what</span>
<span style="color:#0080ff;font-style:italic"># subcommand was invoked</span>
subparsers <span style="color:#2c5dcd">=</span> parser<span style="color:#2c5dcd">.</span>add_subparsers(dest<span style="color:#2c5dcd">=</span><span style="color:#0c6">'command'</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'Sub-commands.'</span>)
parser_subcmd_foo <span style="color:#2c5dcd">=</span> subparsers<span style="color:#2c5dcd">.</span>add_parser(<span style="color:#0c6">'add'</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'Add two numbers together.'</span>)
parser_subcmd_foo<span style="color:#2c5dcd">.</span>add_argument(<span style="color:#0c6">'num1'</span>, <span style="color:#5918bb;font-weight:bold">type</span><span style="color:#2c5dcd">=</span><span style="color:#5918bb;font-weight:bold">int</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'First number to add.'</span>)
parser_subcmd_foo<span style="color:#2c5dcd">.</span>add_argument(<span style="color:#0c6">'num2'</span>, <span style="color:#5918bb;font-weight:bold">type</span><span style="color:#2c5dcd">=</span><span style="color:#5918bb;font-weight:bold">int</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'Second number to add.'</span>)
parser_subcmd_bar <span style="color:#2c5dcd">=</span> subparsers<span style="color:#2c5dcd">.</span>add_parser(<span style="color:#0c6">'print'</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'Print a message.'</span>)
parser_subcmd_bar<span style="color:#2c5dcd">.</span>add_argument(<span style="color:#0c6">'message'</span>, help<span style="color:#2c5dcd">=</span><span style="color:#0c6">'Message to print.'</span>)
args <span style="color:#2c5dcd">=</span> parser<span style="color:#2c5dcd">.</span>parse_args()
<span style="color:#2c5dcd;font-weight:bold">if</span> args<span style="color:#2c5dcd">.</span>command <span style="color:#2c5dcd">==</span> <span style="color:#0c6">'add'</span>:
<span style="color:#5918bb;font-weight:bold">print</span>(<span style="color:#0c6">f</span><span style="color:#0c6">'</span><span style="color:#0c6">{</span>args<span style="color:#2c5dcd">.</span>num1 <span style="color:#2c5dcd">+</span> args<span style="color:#2c5dcd">.</span>num2<span style="color:#0c6">}</span><span style="color:#0c6">'</span>)
<span style="color:#2c5dcd;font-weight:bold">elif</span> args<span style="color:#2c5dcd">.</span>command <span style="color:#2c5dcd">==</span> <span style="color:#0c6">'print'</span>:
<span style="color:#5918bb;font-weight:bold">print</span>(args<span style="color:#2c5dcd">.</span>message)
if name == 'main':
main()
|
The following code shows how this Python file can be called with command-line arguments from a shell/terminal:
1
2
3
4
5
|
$ my_program.py add 1 2
3
$ my_program.py print hello
hello
|
argparse
also provides nice help for these sub-commands:
1
2
3
4
5
6
7
8
9
10
11
12
|
$ ./my_program.py -h
usage: my_program.py [-h] {add,print} ...
Example argument parser with sub-commands.
positional arguments:
{add,print} Sub-commands.
add Add two numbers together.
print Print a message.
optional arguments:
-h, –help show this help message and exit
|