Original published in Prodesire blog.

Preface

Have you ever wondered how a command is parsed and executed after typing it into the command line? Have you ever considered implementing a command-line tool to help you execute and process tasks? Have you ever learned that Python, which accompanies you, has a rich library to help you easily build command-line tools?

Don't worry, as the first part of Python command line tour, this article will take you step by step to uncover the veil of command line parsing, introduce how to use Python's built-in argparse standard library to parse command line, and introduce each characteristic third-party command line library in the following series of articles, explain their similarities and differences, and then fully experience the journey of this exploration.

Python 3 is the default interpreter for this series of articles.
If you are still using Python 2, please pay attention to the differences in syntax and library usage between the two~

introduce

Argparse, as Python's built-in standard library, provides a relatively simple way to write command-line interfaces. When you define which parameters are needed in the program, argparse will obtain command line input from sys.argv for parsing, respond to correct or illegal input, and automatically generate help information and instructions.

Quick start

Set up parser

The first step is to set up a parser. Subsequent parsing of the command line depends on the parser, which can convert command-line strings into Python objects.
By instantiating argparse.ArgumentParser, given some optional parameters, we can set a parser:

import argparse
parser = argparse.ArgumentParser(
    description='My Cmd Line Program',
)

Defining parameters

The ArgumentParser.add_argument method is used to set parameter information for the parser to tell the parser which content in the command line string should be resolved to which types of Python objects, such as:

# Add the nums parameter and display it as num in the usage information
# It is of type int, supports multiple inputs, and at least one needs to be provided
parser.add_argument('nums',  metavar='num', type=int, nargs='+',
                    help='a num for the accumulator')
# Add the -- sum parameter. After the parameter is parsed by the parser, the corresponding property name is accumulate
# If -- sum is not provided, the default value is the max function, otherwise it is the sum function
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the nums (default: find the max)')

Parsing the command line

Once the parameters are defined, you can use the argumenteparser.parse_argsmethod to parse a set of command-line parameter strings.

By default, the parameter is taken from sys.argv[1:], which is a string list corresponding to a command (excluding file name) that you type on the command line.
For example, if you enter Python 3 cmd.py -- sum 1 2 3, sys.argsv[1:] is ['-- sum', '1', '2', '3'].

Of course, you can also specify a set of command-line parameter strings through the parse ﹣ args input parameter:

args = parser.parse_args(['--sum', '-1', '0', '1'])
print(args) # Results: namespace (accumulate = < build in function sum >, nums = [- 1, 0, 1])

Business logic

After parsing the command line, we can get the value of each parameter from the parsing result, and then we can do further processing according to our own business requirements.
For example, for the nums parameter defined above, we can maximize or sum it through the accumulate method in the parsed result (depending on whether the -- sum parameter is provided).

result = args.accumulate(args.nums)
print(result)  # Based on the above ['-- sum', '- 1','0 ','1'] parameters, accumulate is the sum function, and the result is 0

Code sorting

Is it easy to understand to complete the steps of a command line tool? We will summarize the above codes to have a clearer understanding:

# cmd.py
import argparse

# 1. Set parser
parser = argparse.ArgumentParser(
    description='My Cmd Line Program',
)

# 2. Define parameters
parser.add_argument('nums',  metavar='num', type=int, nargs='+',
                    help='a num for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the nums (default: find the max)')

# 3. Parsing command line
args = parser.parse_args()

# 4. Business logic
result = args.accumulate(args.nums)
print(result)

If we need to sum a set of numbers, we just need to perform:

$ python3 cmd.py --sum -1 0 1
0

If we need to maximize a set of numbers, just do the following:

$ python3 cmd.py -1 0 1
1

If the given parameter is not a number, an error message will be given:

$ python3 cmd.py a b c
usage: cmd.py [-h] [--sum] num [num ...]
cmd.py: error: argument num: invalid int value: 'a'

We can also view the automatically generated instructions and help through the - h or -- help parameter:

usage: cmd.py [-h] [--sum] num [num ...]

My Cmd Line Program

positional arguments:
  num         a num for the accumulator

optional arguments:
  -h, --help  show this help message and exit
  --sum       sum the nums (default: find the max)

Summary

What about? After unveiling the mysteries of command-line tools, do you find that they are not as difficult as you think? But feel a simple and powerful elegance?

But this is far from the whole face of argparse. For some complex cases, such as various types of parameters, parameter prefixes, parameter groups, mutually exclusive options, nested parsing, custom help, etc., we have not discussed them.

In the next article, let's have a deeper understanding of argparse and feel its charm!