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.

Note

Passing in dest='command' to add_subparsers() allows us to query the sub-command invoked through args.command.

Note

#!/usr/bin/env python3
import argparse

def main():
    parser = argparse.ArgumentParser(description='Example argument parser with sub-commands.')

<span style="color:#75715e"># Setting dest=&#39;command&#39; means we can later check args.command to see what</span>
<span style="color:#75715e"># subcommand was invoked</span>
subparsers <span style="color:#f92672">=</span> parser<span style="color:#f92672">.</span>add_subparsers(dest<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;command&#39;</span>, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;Sub-commands.&#39;</span>)

parser_subcmd_foo <span style="color:#f92672">=</span> subparsers<span style="color:#f92672">.</span>add_parser(<span style="color:#e6db74">&#39;add&#39;</span>, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;Add two numbers together.&#39;</span>)
parser_subcmd_foo<span style="color:#f92672">.</span>add_argument(<span style="color:#e6db74">&#39;num1&#39;</span>, type<span style="color:#f92672">=</span>int, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;First number to add.&#39;</span>)
parser_subcmd_foo<span style="color:#f92672">.</span>add_argument(<span style="color:#e6db74">&#39;num2&#39;</span>, type<span style="color:#f92672">=</span>int, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;Second number to add.&#39;</span>)

parser_subcmd_bar <span style="color:#f92672">=</span> subparsers<span style="color:#f92672">.</span>add_parser(<span style="color:#e6db74">&#39;print&#39;</span>, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;Print a message.&#39;</span>)
parser_subcmd_bar<span style="color:#f92672">.</span>add_argument(<span style="color:#e6db74">&#39;message&#39;</span>, help<span style="color:#f92672">=</span><span style="color:#e6db74">&#39;Message to print.&#39;</span>)

args <span style="color:#f92672">=</span> parser<span style="color:#f92672">.</span>parse_args()

<span style="color:#66d9ef">if</span> args<span style="color:#f92672">.</span>command <span style="color:#f92672">==</span> <span style="color:#e6db74">&#39;add&#39;</span>:
    <span style="color:#66d9ef">print</span>(f<span style="color:#e6db74">&#39;{args.num1 + args.num2}&#39;</span>)
<span style="color:#66d9ef">elif</span> args<span style="color:#f92672">.</span>command <span style="color:#f92672">==</span> <span style="color:#e6db74">&#39;print&#39;</span>:
    <span style="color:#66d9ef">print</span>(args<span style="color:#f92672">.</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:

$ my_program.py add 1 2 3

$ my_program.py print hello hello

argparse also provides nice help for these sub-commands:

$ ./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

Like this page? Upvote with shurikens!

Recent Updates:

Convex Hull Algorithms

Passive Filters

Python Debugging

pandas

pytest

Parsing Command-Line Arguments In Python

Overview

Sub-Commands

Related Content:

Tags: