Construct Command-Line Interfaces With Python’s argparse – Actual Python

Command-Line Interfaces (CLIs)

Command-line interfaces will let you work together with an utility or program by your working system command line, terminal, or console.

To know command-line interfaces and the way they work, contemplate this sensible instance. Say that you’ve a listing referred to as pattern containing three pattern recordsdata. If you happen to’re on a Unix-like working system, similar to Linux or macOS, go forward and open a command-line window or terminal within the mother or father listing after which execute the next command:

$ ls pattern/
hey.txt     lorem.md      realpython.md

The ls Unix command lists the recordsdata and subdirectories contained in a goal listing, which defaults to the present working listing. The above command name doesn’t show a lot details about the content material of pattern. It solely shows the filenames on the display.

PS> ls .pattern

    Listing: C:pattern

Mode                 LastWriteTime         Size Identify
----                 -------------         ------ ----
-a---          11/10/2022 10:06 AM             88 hey.txt
-a---          11/10/2022 10:06 AM           2629 lorem.md
-a---          11/10/2022 10:06 AM            429 realpython.md

Suppose you need richer details about your listing and its content material. In that case, you don’t want to go searching for a program aside from ls as a result of this command has a full-featured command-line interface with a helpful set of choices that you should utilize to customise the command’s habits.

For instance, go forward and execute ls with the -l choice:

$ ls -l pattern/
complete 24
-rw-r--r--@ 1 consumer  workers    83 Aug 17 22:15 hey.txt
-rw-r--r--@ 1 consumer  workers  2609 Aug 17 22:15 lorem.md
-rw-r--r--@ 1 consumer  workers   428 Aug 17 22:15 realpython.md

The output of ls is kind of totally different now. The command shows far more details about the recordsdata in pattern, together with permissions, proprietor, group, date, and dimension. It additionally reveals the full area that these recordsdata use in your pc’s disk.

This richer output outcomes from utilizing the -l choice, which is a part of the Unix ls command-line interface and permits the detailed output format.

Instructions, Arguments, Choices, Parameters, and Subcommands

All through this tutorial, you’ll study instructions and subcommands. You’ll additionally study command-line arguments, choices, and parameters, so you need to incorporate these phrases into your tech vocabulary:

• Command: A program or routine that runs on the command line or terminal window. You’ll sometimes determine a command with the identify of the underlying program or routine.

• Argument: A required or non-obligatory piece of data {that a} command makes use of to carry out its meant motion. Instructions sometimes settle for one or many arguments, which you’ll be able to present as a whitespace-separated or comma-separated listing in your command line.

• Possibility, often known as flag or swap: An non-obligatory argument that modifies a command’s habits. Choices are handed to instructions utilizing a particular identify, like -l within the earlier instance.

• Parameter: An argument that an choice makes use of to carry out its meant operation or motion.

• Subcommand: A predefined identify that may be handed to an utility to run a particular motion.

Think about the pattern command assemble from the earlier part:

On this instance, you’ve mixed the next elements of a CLI:

• ls: The command’s identify or the app’s identify
• -l: An choice, swap, or flag that allows detailed outputs
• pattern: An argument that gives extra data to the command’s execution

Now contemplate the next command assemble, which showcases the CLI of Python’s package deal supervisor, referred to as pip:

$ pip set up -r necessities.txt

This can be a widespread pip command assemble, which you’ve in all probability seen earlier than. It means that you can set up the necessities of a given Python mission utilizing a necessities.txt file. On this instance, you’re utilizing the next CLI elements:

• pip: The command’s identify
• set up: The identify of a subcommand of pip
• -r: An choice of the set up subcommand
• necessities.txt: An argument, particularly a parameter of the -r choice

Now you already know what command-line interfaces are and what their essential elements or elements are. It’s time to discover ways to create your individual CLIs in Python.

Utilizing sys.argv to Construct a Minimal CLI

For instance of utilizing argv to create a minimal CLI, say that you could write a small program that lists all of the recordsdata in a given listing, just like what ls does. On this state of affairs, you’ll be able to write one thing like this:

# ls_argv.py

import sys
from pathlib import Path

if (args_count := len(sys.argv)) > 2:
    print(f"One argument anticipated, obtained {args_count - 1}")
    increase SystemExit(2)
elif args_count < 2:
    print("You should specify the goal listing")
    increase SystemExit(2)

target_dir = Path(sys.argv[1])

if not target_dir.is_dir():
    print("The goal listing does not exist")
    increase SystemExit(1)

for entry in target_dir.iterdir():
    print(entry.identify)

This program implements a minimal CLI by manually processing the arguments offered on the command line, that are routinely saved in sys.argv. The primary merchandise in sys.argv is all the time this system’s identify. The second merchandise would be the goal listing. The app shouldn’t settle for multiple goal listing, so the args_count should not exceed 2.

After checking the content material of sys.argv, you create a pathlib.Path object to retailer the trail to your goal listing. If this listing doesn’t exist, then you definitely inform the consumer and exit the app. The for loop lists the listing content material, one entry per line.

If you happen to run the script out of your command line, then you definitely’ll get the next outcomes:

$ python ls_argv.py pattern/
hey.txt
lorem.md
realpython.md

$ python ls_argv.py
You should specify the goal listing

$ python ls_argv.py pattern/ other_dir/
One argument anticipated, obtained 2

$ python ls_argv.py non_existing/
The goal listing does not exist

Your program takes a listing as an argument and lists its content material. If you happen to run the command with out arguments, then you definitely get an error message. If you happen to run the command with multiple goal listing, you additionally get an error. Operating the command with a nonexistent listing produces one other error message.

Despite the fact that your program works okay, parsing command-line arguments manually utilizing the sys.argv attribute isn’t a scalable answer for extra complicated CLI apps. In case your app must take many extra arguments and choices, then parsing sys.argv will likely be a posh and error-prone process. You want one thing higher, and also you get it in Python’s argparse module.

Making a CLI With argparse

A way more handy strategy to create CLI apps in Python is utilizing the argparse module, which comes within the customary library. This module was first launched in Python 3.2 with PEP 389 and is a fast strategy to create CLI apps in Python with out putting in a third-party library, similar to Typer or Click on.

This module was launched as a alternative for the older getopt and optparse modules as a result of they lacked some vital options.

Python’s argparse module means that you can:

• Parse command-line arguments and choices
• Take a variable variety of parameters in a single choice
• Present subcommands in your CLIs

These options flip argparse into a robust CLI framework which you could confidently depend on when creating your CLI functions. To make use of Python’s argparse, you’ll have to observe 4 simple steps:

1. Import argparse.
2. Create an argument parser by instantiating ArgumentParser.
3. Add arguments and choices to the parser utilizing the .add_argument() methodology.
4. Name .parse_args() on the parser to get the Namespace of arguments.

For instance, you should utilize argparse to enhance your ls_argv.py script. Go forward and create ls.py with the next code:

# ls.py v1

import argparse
from pathlib import Path

parser = argparse.ArgumentParser()

parser.add_argument("path")

args = parser.parse_args()

target_dir = Path(args.path)

if not target_dir.exists():
    print("The goal listing does not exist")
    increase SystemExit(1)

for entry in target_dir.iterdir():
    print(entry.identify)

Your code has modified considerably with the introduction of argparse. Essentially the most notable distinction from the earlier model is that the conditional statements to test the arguments offered by the consumer are gone. That’s as a result of argparse routinely checks the presence of arguments for you.

On this new implementation, you first import argparse and create an argument parser. To create the parser, you utilize the ArgumentParser class. Subsequent, you outline an argument referred to as path to get the consumer’s goal listing.

The following step is to name .parse_args() to parse the enter arguments and get a Namespace object that accommodates all of the consumer’s arguments. Observe that now the args variable holds a Namespace object, which has a property for every argument that’s been gathered from the command line.

On this instance, you solely have one argument, referred to as path. The Namespace object means that you can entry path utilizing the dot notation on args. The remainder of your code stays the identical as within the first implementation.

Now go forward and run this new script out of your command line:

$ python ls.py pattern/
lorem.md
realpython.md
hey.txt

$ python ls.py
utilization: ls.py [-h] path
ls.py: error: the next arguments are required: path

$ python ls.py pattern/ other_dir/
utilization: ls.py [-h] path
ls.py: error: unrecognized arguments: other_dir/

$ python ls.py non_existing/
The goal listing does not exist

The primary command prints the identical output as your unique script, ls_argv.py. In distinction, the second command shows output that’s fairly totally different from in ls_argv.py. This system now reveals a utilization message and points an error telling you that it’s essential to present the path argument.

Within the third command, you cross two goal directories, however the app isn’t ready for that. Subsequently, it reveals the utilization message once more and throws an error letting you already know concerning the underlying drawback.

Lastly, if you happen to run the script with a nonexistent listing as an argument, then you definitely get an error telling you that the goal listing doesn’t exist, so this system can’t do its work.

A brand new implicit characteristic is now out there to you. Now your program accepts an non-obligatory -h flag. Go forward and provides it a attempt:

$ python ls.py -h
utilization: ls.py [-h] path

positional arguments:
  path

choices:
  -h, --help  present this assist message and exit

Nice, now your program routinely responds to the -h or --help flag, displaying a assist message with utilization directions for you. That’s a very neat characteristic, and also you get it at no cost by introducing argparse into your code!

With this fast introduction to creating CLI apps in Python, you’re now able to dive deeper into the argparse module and all its cool options.

Making a Command-Line Argument Parser

The command-line argument parser is an important a part of any argparse CLI. All of the arguments and choices that you just present on the command line will cross by this parser, which is able to do the onerous give you the results you want.

To create a command-line argument parser with argparse, you could instantiate the ArgumentParser class:

>>> from argparse import ArgumentParser

>>> parser = ArgumentParser()
>>> parser
ArgumentParser(
    prog='',
    utilization=None,
    description=None,
    formatter_class=<class 'argparse.HelpFormatter'>,
    conflict_handler='error',
    add_help=True
)

The constructor of ArgumentParser takes many alternative arguments that you should utilize to tweak a number of options of your CLIs. All of its arguments are non-obligatory, so essentially the most bare-bones parser which you could create outcomes from instantiating ArgumentParser with none arguments.

You’ll be taught extra concerning the arguments to the ArgumentParser constructor all through this tutorial, significantly within the part on customizing your argument parser. For now, you’ll be able to deal with the subsequent step in making a CLI with argparse. That step is so as to add arguments and choices by the parser object.

Including Arguments and Choices

So as to add arguments and choices to an argparse CLI, you’ll use the .add_argument() methodology of your ArgumentParser occasion. Observe that the tactic is widespread for arguments and choices. Do not forget that within the argparse terminology, arguments are referred to as positional arguments, and choices are referred to as non-obligatory arguments.

The primary argument to the .add_argument() methodology units the distinction between arguments and choices. This argument is recognized as both identify or flag. So, if you happen to present a identify, then you definitely’ll be defining an argument. In distinction, if you happen to use a flag, then you definitely’ll add an choice.

You’ve already labored with command-line arguments in argparse. So, contemplate the next enhanced model of your customized ls command, which provides an -l choice to the CLI:

 1# ls.py v2
 2
 3import argparse
 4import datetime
 5from pathlib import Path
 6
 7parser = argparse.ArgumentParser()
 8
 9parser.add_argument("path")
10
11parser.add_argument("-l", "--long", motion="store_true")
12
13args = parser.parse_args()
14
15target_dir = Path(args.path)
16
17if not target_dir.exists():
18    print("The goal listing does not exist")
19    increase SystemExit(1)
20
21def build_output(entry, lengthy=False):
22    if lengthy:
23        dimension = entry.stat().st_size
24        date = datetime.date.fromtimestamp(entry.stat().st_mtime).strftime(
25            "%b %d %m:%S"
26        )
27        return f"{dimension:>6d} {date} {entry.identify}"
28    return entry.identify
29
30for entry in target_dir.iterdir():
31    print(build_output(entry, lengthy=args.lengthy))

On this instance, line 11 creates an choice with the flags -l and --long. The syntactical distinction between arguments and choices is that choice names begin with - for shorthand flags and -- for lengthy flags.

Observe that on this particular instance, an motion argument set to "store_true" accompanies the -l or --long choice, which signifies that this feature will retailer a Boolean worth. If you happen to present the choice on the command line, then its worth will likely be True. If you happen to miss the choice, then its worth will likely be False. You’ll be taught extra concerning the motion argument to .add_argument() within the Setting the Motion Behind an Possibility part.

The build_output() operate on line 21 returns an in depth output when lengthy is True and a minimal output in any other case. The detailed output will include the dimensions, modification date, and identify of all of the entries within the goal listing. It makes use of instruments just like the Path.stat() and a datetime.date object with a customized string format.

Go forward and execute your program on pattern to test how the -l choice works:

$ python ls.py -l pattern/
  2609 Oct 28 10:00 lorem.md
   428 Oct 28 10:00 realpython.md
    83 Oct 28 10:00 hey.txt

Your new -l choice means that you can generate and show a extra detailed output concerning the content material of your goal listing.

Now that you know the way so as to add command-line arguments and choices to your CLIs, it’s time to dive into parsing these arguments and choices. That’s what you’ll discover within the following part.

Parsing Command-Line Arguments and Choices

Parsing the command-line arguments is one other vital step in any CLI app primarily based on argparse. When you’ve parsed the arguments, then you can begin taking motion in response to their values. In your customized ls command instance, the argument parsing occurs on the road containing the args = parser.parse_args() assertion.

This assertion calls the .parse_args() methodology and assigns its return worth to the args variable. The return worth of .parse_args() is a Namespace object containing all of the arguments and choices offered on the command line and their corresponding values.

Think about the next toy instance:

>>> from argparse import ArgumentParser

>>> parser = ArgumentParser()

>>> parser.add_argument("website")
_StoreAction(...)

>>> parser.add_argument("-c", "--connect", motion="store_true")
_StoreTrueAction(...)

>>> args = parser.parse_args(["Real Python", "-c"])
>>> args
Namespace(website='Actual Python', join=True)

>>> args.website
'Actual Python'
>>> args.join
True

The Namespace object that outcomes from calling .parse_args() on the command-line argument parser provides you entry to all of the enter arguments, choices, and their corresponding values by utilizing the dot notation. This fashion, you’ll be able to test the listing of enter arguments and choices to take actions in response to the consumer’s selections on the command line.

You’ll use this Namespace object in your utility’s essential code. That’s what you probably did beneath the for loop in your customized ls command instance.

Up so far, you’ve discovered about the principle steps for creating argparse CLIs. Now you’ll be able to take a while to be taught the fundamentals of easy methods to manage and construct a CLI utility in Python.

Setting Up Your CLI App’s Format and Construct System

Earlier than persevering with together with your argparse studying journey, you need to pause and consider how you’ll manage your code and lay out a CLI mission. First, you need to observe the next factors:

• You possibly can create modules and packages to prepare your code.
• You possibly can identify the core package deal of a Python app after the app itself.
• You’ll identify every Python module in response to its particular content material or performance.
• You possibly can add a __main__.py module to any Python package deal if you wish to make that package deal instantly executable.

With these concepts in thoughts and contemplating that the model-view-controller (MVC) sample is an efficient strategy to construction your functions, you should utilize the next listing construction when laying out a CLI mission:

hello_cli/
│
├── hello_cli/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   └── mannequin.py
│
├── checks/
│   ├── __init__.py
│   ├── test_cli.py
│   └── test_model.py
│
├── pyproject.toml
├── README.md
└── necessities.txt

The hello_cli/ listing is the mission’s root listing. There, you’ll place the next recordsdata:

• pyproject.toml is a TOML file that specifies the mission’s construct system and different configurations.
• README.md supplies the mission description and directions for putting in and working the appliance. Including a descriptive and detailed README.md file to your initiatives is a greatest apply in programming, particularly if you happen to’re planning to launch the mission as an open-source answer.
• necessities.txt supplies a traditional file that lists the mission’s exterior dependencies. You’ll use this file to routinely set up the dependencies utilizing pip with the -r choice.

Then you could have the hello_cli/ listing that holds the app’s core package deal, which accommodates the next modules:

• __init__.py permits hello_cli/ as a Python package deal.
• __main__.py supplies the appliance’s entry-point script or executable file.
• cli.py supplies the appliance’s command-line interface. The code on this file will play the view-controller function within the MVC-based structure.
• mannequin.py accommodates the code that helps the app’s essential functionalities. This code will play the mannequin function in your MVC structure.

You’ll even have a checks/ package deal containing recordsdata with unit checks to your app’s elements. On this particular mission structure instance, you could have test_cli.py for unit checks that test the CLI’s performance and test_model.py for unit checks that test your mannequin’s code.

The pyproject.toml file means that you can outline the app’s construct system in addition to many different basic configurations. Right here’s a minimal instance of easy methods to fill on this file to your pattern hello_cli mission:

# pyproject.toml

[build-system]
requires = ["setuptools>=64.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
identify = "hello_cli"
model = "0.0.1"
description = "My superior Hey CLI utility"
readme = "README.md"
authors = [{ name = "Real Python", email = "info@realpython.com" }]

[project.scripts]
hello_cli = "hello_cli.__main__:essential"

The [build-system] desk header units up setuptools as your app’s construct system and specifies which dependencies Python wants to put in for constructing your app. The [project] header supplies basic metadata to your utility. This metadata is fairly helpful if you need to publish your app to the Python package deal index (PyPI). Lastly, the [project.scripts] heading defines the entry level to your utility.

With this fast dive into laying out and constructing CLI initiatives, you’re able to proceed studying about argparse, particularly easy methods to customise your command-line argument parser.

Tweaking the Program’s Assist and Utilization Content material

Offering utilization directions and assist to the customers of your CLI functions is a greatest apply that’ll make your customers’ lives extra nice with an awesome consumer expertise (UX). On this part, you’ll discover ways to reap the benefits of some arguments of ArgumentParser to fine-tune how your CLI apps present assist and utilization messages to their customers. You’ll discover ways to:

• Set this system’s identify
• Outline this system’s description and epilog message
• Show grouped assist for arguments and choices

To kick issues off, you’ll begin by setting your program’s identify and specifying how that identify will look within the context of a assist or utilization message.

$ python ls.py -h
utilization: ls.py [-h] [-l] path

positional arguments:
  path

choices:
  -h, --help  present this assist message and exit
  -l, --long

# ls.py v3

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(prog="ls")

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, lengthy=args.lengthy))

$ python ls.py -h
utilization: ls [-h] [-l] path

positional arguments:
  path

choices:
  -h, --help  present this assist message and exit
  -l, --long

# ls.py v4

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(
    prog="ls",
    description="Listing the content material of a listing",
    epilog="Thanks for utilizing %(prog)s! :)",
)

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, lengthy=args.lengthy))

$ python ls.py -h
utilization: ls [-h] [-l] path

Listing the content material of a listing

positional arguments:
  path

choices:
  -h, --help  present this assist message and exit
  -l, --long

Thanks for utilizing ls! :)

# ls.py v5
# ...

parser = argparse.ArgumentParser(
    prog="ls",
    description="Listing the content material of a listing",
    epilog="Thanks for utilizing %(prog)s! :)",
)

basic = arg_parser.add_argument_group("basic output")
basic.add_argument("path")

detailed = arg_parser.add_argument_group("detailed output")
detailed.add_argument("-l", "--long", motion="store_true")

args = arg_parser.parse_args()

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, lengthy=args.lengthy))

python ls.py -h
utilization: ls [-h] [-l] path

Listing the content material of a listing

choices:
  -h, --help  present this assist message and exit

basic output:
  path

detailed output:
  -l, --long

Thanks for utilizing ls! :)

Offering World Settings for Arguments and Choices

Past customizing the utilization and assist messages, ArgumentParser additionally means that you can carry out just a few different attention-grabbing tweaks to your CLI apps. A few of these tweaks embody:

• Defining a worldwide default worth for arguments and choices
• Loading arguments and choices from an exterior file
• Permitting or disallowing choice abbreviations

Generally, chances are you’ll have to specify a single international default worth to your app’s arguments and choices. You are able to do this by passing the default worth to argument_default on the decision to the ArgumentParser constructor.

This characteristic could also be solely not often helpful as a result of arguments and choices usually have a unique knowledge sort or which means, and it may be tough to discover a worth that fits all the necessities.

Nonetheless, a typical use case of argument_default is if you need to keep away from including arguments and choices to the Namespace object. On this state of affairs, you should utilize the SUPPRESS fixed because the default worth. This default worth will make it in order that solely the arguments and choices offered on the command line find yourself saved within the arguments Namespace.

For instance, go forward and modify your customized ls command as within the snippet under:

# ls.py v6

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(
    prog="ls",
    description="Listing the content material of a listing",
    epilog="Thanks for utilizing %(prog)s! :)",
    argument_default=argparse.SUPPRESS,
)

# ...

for entry in target_dir.iterdir():
    attempt:
        lengthy = args.lengthy
    besides AttributeError:
        lengthy = False
    print(build_output(entry, lengthy=lengthy))

By passing SUPPRESS to the ArgumentParser constructor, you stop non-supplied arguments from being saved within the arguments Namespace object. That’s why you must test if the -l or --long choice was truly handed earlier than calling build_output(). In any other case, your code will break with an AttributeError as a result of lengthy gained’t be current in args.

One other cool characteristic of ArgumentParser is that it means that you can load argument values from an exterior file. This risk turns out to be useful when you could have an utility with lengthy or sophisticated command-line constructs, and also you need to automate the method of loading argument values.

On this state of affairs, you’ll be able to retailer the argument values in an exterior file and ask your program to load them from it. To do this characteristic out, go forward and create the next toy CLI app:

# fromfile.py

import argparse

parser = argparse.ArgumentParser(fromfile_prefix_chars="@")

parser.add_argument("one")
parser.add_argument("two")
parser.add_argument("three")

args = parser.parse_args()

print(args)

Right here, you cross the @ image to the fromfile_prefix_chars argument of ArgumentParser. You then create three required arguments that have to be offered on the command line.

Now say that you just usually use this utility with the identical set of argument values. To facilitate and streamline your work, you’ll be able to create a file containing applicable values for all the required arguments, one per line, like within the following args.txt file:

With this file in place, now you can name your program and instruct it to load the values from the args.txt file like within the following command run:

$ python fromfile.py @args.txt
Namespace(one='first', two='second', three='third')

On this command’s output, you’ll be able to see that argparse has learn the content material of args.txt and sequentially assigned values to every argument of your fromfile.py program. All of the arguments and their values are efficiently saved within the Namespace object.

The flexibility to simply accept abbreviated choice names is one other cool characteristic of argparse CLIs. This characteristic is enabled by default and turns out to be useful when your program has lengthy choice names. For instance, contemplate the next program, which prints out the worth that you just specify on the command line beneath the --argument-with-a-long-name choice:

# abbreviate.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--argument-with-a-long-name")

args = parser.parse_args()

print(args.argument_with_a_long_name)

This program prints no matter your cross as an argument to the --argument-with-a-long-name choice. Go forward and run the next instructions to test how the Python argparse module handles abbreviations for you:

$ python abbreviate.py --argument-with-a-long-name 42
42

$ python abbreviate.py --argument 42
42

$ python abbreviate.py --a 42
42

These examples present how one can abbreviate the identify of the --argument-with-a-long-name choice and nonetheless get the app to work accurately. This characteristic is enabled by default. If you wish to disable it and forbid abbreviations, then you should utilize the allow_abbrev argument to ArgumentParser:

# abbreviate.py

import argparse

parser = argparse.ArgumentParser(allow_abbrev=False)

parser.add_argument("--argument-with-a-long-name")

args = parser.parse_args()

print(args.argument_with_a_long_name)

Setting allow_abbrev to False disables abbreviations in command-line choices. From this level on, you’ll have to supply the whole choice identify for this system to work accurately. In any other case, you’ll get an error:

$ python abbreviate.py --argument-with-a-long-name 42
42

$ python abbreviate.py --argument 42
utilization: abbreviate.py [-h] [--argument-with-a-long-name ...]
abbreviate.py: error: unrecognized arguments: --argument 42

The error message within the second instance tells you that the --argument choice isn’t acknowledged as a sound choice. To make use of the choice, you could present its full identify.

Setting the Motion Behind an Possibility

If you add an choice or flag to a command-line interface, you’ll usually have to outline the way you need to retailer the choice’s worth within the Namespace object that outcomes from calling .parse_args(). To do that, you’ll use the motion argument to .add_argument(). The motion argument defaults to "retailer", which signifies that the worth offered for the choice at hand will likely be saved as is within the Namespace.

The motion argument can take one in every of a number of potential values. Right here’s the listing of those potential values and their meanings:

On this desk, the values that embody the _const suffix of their names require you to supply the specified fixed worth utilizing the const argument within the name to the .add_argument() methodology. Equally, the model motion requires you to supply the app’s model by passing the model argument to .add_argument(). You must also notice that solely the retailer and append actions can and should take arguments on the command line.

To attempt these actions out, you’ll be able to create a toy app with the next implementation:

# actions.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    "--name", motion="retailer"
)  # Equal to parser.add_argument("--name")
parser.add_argument("--pi", motion="store_const", const=3.14)
parser.add_argument("--is-valid", motion="store_true")
parser.add_argument("--is-invalid", motion="store_false")
parser.add_argument("--item", motion="append")
parser.add_argument("--repeated", motion="append_const", const=42)
parser.add_argument("--add-one", motion="rely")
parser.add_argument(
    "--version", motion="model", model="%(prog)s 0.1.0"
)

args = parser.parse_args()

print(args)

This program implements an choice for every sort of motion mentioned above. Then this system prints the ensuing Namespace of arguments. Right here’s a abstract of how these choices will work:

• --name will retailer the worth handed, with none additional consideration.

• --pi will routinely retailer the goal fixed when the choice is offered.

• --is-valid will retailer True when offered and False in any other case. If you happen to want the alternative habits, use a store_false motion like --is-invalid on this instance.

• --item will allow you to create an inventory of all of the values. You should repeat the choice for every worth. Below the hood, argparse will append the gadgets to an inventory named after the choice itself.

• --repeated will work equally to --item. Nonetheless, it all the time appends the identical fixed worth, which it’s essential to present utilizing the const argument.

• --add-one counts what number of occasions the choice is handed on the command line. The sort of choice is kind of helpful if you need to implement a number of verbosity ranges in your packages. For instance, -v can imply stage one in every of verbosity, -vv might point out stage two, and so forth.

• --version reveals the app’s model and terminates the execution instantly. Observe that it’s essential to present the model quantity beforehand, which you are able to do by utilizing the model argument when creating the choice with .add_argument().

Go forward and run the script with the next command assemble to check out all these choices:

PS> python actions.py `
>   --name Python `
>   --pi `
>   --is-valid `
>   --is-invalid `
>   --item 1 --item 2 --item 3 `
>   --repeat --repeat --repeat `
>   --add-one --add-one --add-one
Namespace(
    identify='Python',
    pi=3.14,
    is_valid=True,
    is_invalid=False,
    merchandise=['1', '2', '3'],
    repeated=[42, 42, 42],
    add_one=3
)

PS> python actions.py --version
actions.py 0.1.0

$ python actions.py 
    --name Python 
    --pi 
    --is-valid 
    --is-invalid 
    --item 1 --item 2 --item 3 
    --repeat --repeat --repeat 
    --add-one --add-one --add-one
Namespace(
    identify='Python',
    pi=3.14,
    is_valid=True,
    is_invalid=False,
    merchandise=['1', '2', '3'],
    repeated=[42, 42, 42],
    add_one=3
)

$ python actions.py --version
actions.py 0.1.0

With this command, you present how all of the actions work and the way they’re saved within the ensuing Namespace object. The model motion is the final one that you just used, as a result of this feature simply reveals the model of this system after which ends the execution. It doesn’t get saved within the Namespace object.

Despite the fact that the default set of actions is kind of full, you even have the opportunity of creating customized actions by subclassing the argparse.Motion class. If you happen to determine to do that, then it’s essential to override the .__call__() methodology, which turns cases into callable objects. Optionally, you’ll be able to override the .__init__() and .format_usage() strategies relying in your wants.

To override the .__call__() methodology, you could be sure that the tactic’s signature consists of the parser, namespace, values, and option_string arguments.

Within the following instance, you implement a minimal and verbose retailer motion that you should utilize when constructing your CLI apps:

# custom_action.py

import argparse

class VerboseStore(argparse.Motion):
    def __call__(self, parser, namespace, values, option_string=None):
        print(f"Storing {values} within the {option_string} choice...")
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser()

parser.add_argument("-n", "--name", motion=VerboseStore)

args = parser.parse_args()

print(args)

On this instance, you outline VerboseStore inheriting from argparse.Motion. You then override the .__call__() methodology to print an informative message and set the goal choice within the namespace of command-line arguments. Lastly, the app prints the namespace itself.

Go forward and run the next command to check out your customized motion:

$ python custom_action.py --name Python
Storing Python within the --name choice...
Namespace(identify='Python')

Nice! Your program now prints out a message earlier than storing the worth offered to the --name choice on the command line. Customized actions just like the one within the above instance will let you fine-tune how your packages’ choices are saved.

To proceed fine-tuning your argparse CLIs, you’ll discover ways to customise the enter worth of command-line arguments and choices within the following part.

Customizing Enter Values in Arguments and Choices

One other widespread requirement if you’re constructing CLI functions is to customise the enter values that arguments and choices will settle for on the command line. For instance, chances are you’ll require {that a} given argument settle for an integer worth, an inventory of values, a string, and so forth.

By default, any argument offered on the command line will likely be handled as a string. Fortuitously, argparse has inside mechanisms to test if a given argument is a sound integer, string, listing, and extra.

On this part, you’ll discover ways to customise the best way wherein argparse processes and shops enter values. Particularly, you’ll discover ways to:

• Set the knowledge sort of enter values for arguments and choices
• Take a number of enter values in arguments and choices
• Present default values for arguments and choices
• Outline an inventory of allowed enter values for arguments and choices

To kick issues off, you’ll begin by customizing the information sort that your arguments and choices will settle for on the command line.

# divide.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--dividend", sort=int)
parser.add_argument("--divisor", sort=int)

args = parser.parse_args()

print(args.dividend / args.divisor)

$ python divide.py --dividend 42 --divisor 2
21.0

$ python divide.py --dividend "42" --divisor "2"
21.0

$ python divide.py --dividend 42 --divisor 2.0
utilization: divide.py [-h] [--dividend DIVIDEND] [--divisor DIVISOR]
divide.py: error: argument --divisor: invalid int worth: '2.0'

$ python divide.py --dividend 42 --divisor two
utilization: divide.py [-h] [--dividend DIVIDEND] [--divisor DIVISOR]
divide.py: error: argument --divisor: invalid int worth: 'two'

# level.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--coordinates", nargs=2)

args = parser.parse_args()

print(args)

$ python level.py --coordinates 2 3
Namespace(coordinates=['2', '3'])

$ python level.py --coordinates 2
utilization: level.py [-h] [--coordinates COORDINATES COORDINATES]
level.py: error: argument --coordinates: anticipated 2 arguments

$ python level.py --coordinates 2 3 4
utilization: level.py [-h] [--coordinates COORDINATES COORDINATES]
level.py: error: unrecognized arguments: 4

$ python level.py --coordinates
utilization: level.py [-h] [--coordinates COORDINATES COORDINATES]
level.py: error: argument --coordinates: anticipated 2 arguments

# sum.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("numbers", nargs="*", sort=float)

args = parser.parse_args()

print(sum(args.numbers))

$ python sum.py 1 2 3
6.0

$ python sum.py 1 2 3 4 5 6
21.0

$ python sum.py
0

# recordsdata.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("recordsdata", nargs="+")

args = parser.parse_args()

print(args)

$ python recordsdata.py hey.txt
Namespace(recordsdata=['hello.txt'])

$ python recordsdata.py hey.txt realpython.md README.md
Namespace(recordsdata=['hello.txt', 'realpython.md', 'README.md'])

$ python recordsdata.py
utilization: recordsdata.py [-h] recordsdata [files ...]
recordsdata.py: error: the next arguments are required: recordsdata

# cooking.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("veggies", nargs="+")
parser.add_argument("fruits", nargs="*")

args = parser.parse_args()

print(args)

$ python cooking.py pepper tomato apple banana
Namespace(veggies=['pepper', 'tomato', 'apple', 'banana'], fruits=[])

# cooking.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--veggies", nargs="+")
parser.add_argument("--fruits", nargs="*")

args = parser.parse_args()

print(args)

$ python cooking.py --veggies pepper tomato --fruits apple banana
Namespace(veggies=['pepper', 'tomato'], fruits=['apple', 'banana'])

# ls.py v7

import argparse
import datetime
from pathlib import Path

# ...

basic = parser.add_argument_group("basic output")
basic.add_argument("path", nargs="?", default=".")

# ...

$ cd pattern/

$ python ../ls.py
lorem.md
realpython.md
hey.txt

# dimension.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--size", selections=["S", "M", "L", "XL"], default="M")

args = parser.parse_args()

print(args)

$ python dimension.py --size S
Namespace(dimension='S')

$ python selections.py --size A
utilization: selections.py [-h] [--size {S,M,L,XL}]
selections.py: error: argument --size: invalid selection: 'A'
    (select from 'S', 'M', 'L', 'XL')

# weekdays.py

import argparse

my_parser = argparse.ArgumentParser()

my_parser.add_argument("--weekday", sort=int, selections=vary(1, 8))

args = my_parser.parse_args()

print(args)

$ python days.py --weekday 2
Namespace(weekday=2)

$ python days.py --weekday 6
Namespace(weekday=6)

$ python days.py --weekday 9
utilization: days.py [-h] [--weekday {1,2,3,4,5,6,7}]
days.py: error: argument --weekday: invalid selection: 9
    (select from 1, 2, 3, 4, 5, 6, 7)

Offering and Customizing Assist Messages in Arguments and Choices

As you already know, an awesome characteristic of argparse is that it generates automated utilization and assist messages to your functions. You possibly can entry these messages utilizing the -h or --help flag, which is included by default in any argparse CLI.

Up so far, you’ve discovered easy methods to present description and epilog messages to your apps. On this part, you’ll proceed bettering your app’s assist and utilization messages by offering enhanced messages for particular person command-line arguments and choices. To do that, you’ll use the assist and metavar arguments of .add_argument().

Return to your customized ls command and run the script with the -h swap to test its present output:

$ python ls.py -h
utilization: ls [-h] [-l] [path]

Listing the content material of a listing

choices:
  -h, --help  present this assist message and exit

basic output:
  path

detailed output:
  -l, --long

Thanks for utilizing ls! :)

This output seems to be good, and it’s a very good instance of how argparse saves you plenty of work by offering utilization and assist message out of the field.

Observe that solely the -h or --help choice reveals a descriptive assist message. In distinction, your individual arguments path and -l or --long don’t present a assist message. To repair that, you should utilize the assist argument.

Open your ls.py and replace it like within the following code:

# ls.py v8

import argparse
import datetime
from pathlib import Path

# ...

basic = parser.add_argument_group("basic output")
basic.add_argument(
    "path",
    nargs="?",
    default=".",
    assist="take the trail to the goal listing (default: %(default)s)",
)

detailed = parser.add_argument_group("detailed output")
detailed.add_argument(
    "-l",
    "--long",
    motion="store_true",
    assist="show detailed listing content material",
)

# ...

On this replace to ls.py, you utilize the assist argument of .add_argument() to supply particular assist messages to your arguments and choices.

Now go forward and run the app with the -h flag once more:

$ python ls.py -h
utilization: ls [-h] [-l] [path]

Listing the content material of a listing

choices:
  -h, --help  present this assist message and exit

basic output:
  path        take the trail to the goal listing (default: .)

detailed output:
  -l, --long  show detailed listing content material

Thanks for utilizing ls! :)

Now each path and -l present descriptive assist messages if you run the app with the -h flag. Observe that path consists of its default worth in its assist message, which supplies helpful data to your customers.

One other desired characteristic is to have a pleasant and readable utilization message in your CLI apps. The default utilization message of argparse is fairly good already. Nonetheless, you should utilize the metavar argument of .add_argument() to barely enhance it.

The metavar argument turns out to be useful when a command-line argument or choice accepts enter values. It means that you can give this enter worth a descriptive identify that the parser can use to generate the assistance message.

For instance of when to make use of metavar, return to your level.py instance:

# level.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--coordinates", nargs=2)

args = parser.parse_args()

print(args)

If you happen to run this utility out of your command line with the -h swap, then you definitely get an output that’ll seem like the next:

$ python level.py -h
utilization: level.py [-h] [--coordinates COORDINATES COORDINATES]

choices:
  -h, --help            present this assist message and exit
  --coordinates COORDINATES COORDINATES

By default, argparse makes use of the unique identify of command-line choices to designate their corresponding enter values within the utilization and assist messages, as you’ll be able to see within the highlighted strains. On this particular instance, the identify COORDINATES within the plural could also be complicated. Ought to your customers present the purpose’s coordinates two occasions?

You possibly can take away this ambiguity by utilizing the metavar argument:

# level.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    "--coordinates",
    nargs=2,
    metavar=("X", "Y"),
    assist="take the Cartesian coordinates %(metavar)s",
)

args = parser.parse_args()

print(args)

On this instance, you utilize a tuple as the worth to metavar. The tuple accommodates the 2 coordinate names that folks generally use to designate a pair of Cartesian coordinates. You additionally present a customized assist message for --coordinates, together with a format specifier with the metavar argument.

If you happen to run the script with the -h flag, then you definitely get the next output:

$ python coordinates.py -h
utilization: coordinates.py [-h] [--coordinates X Y]

choices:
  -h, --help         present this assist message and exit
  --coordinates X Y  take the Cartesian coordinates ('X', 'Y')

Now your app’s utilization and assist messages are method clearer than earlier than. Now your customers will instantly know that they should present two numeric values, X and Y, for the --coordinates choice to work accurately.