Command-Line Interfaces (CLIs)

Command-line interfaces allow you to interact with an application or program through your operating system command line,terminal, or console.

To understand command-line interfaces and how they work, consider this practical example. Say that you have a directory calledsample containing three sample files. If you’re on aUnix-like operating system, such as Linux or macOS, go ahead and open a command-line window or terminal in the parent directory and then execute the following command:

$lssample/hello.txt     lorem.md      realpython.md

Thels Unix command lists the files and subdirectories contained in a target directory, which defaults to the current working directory. The above command call doesn’t display much information about the content ofsample. It only displays the filenames on the screen.

PS>ls.\sample\    Directory: C:\sampleMode                 LastWriteTime         Length Name----                 -------------         ------ -----a---          11/10/2022 10:06 AM             88 hello.txt-a---          11/10/2022 10:06 AM           2629 lorem.md-a---          11/10/2022 10:06 AM            429 realpython.md

Suppose you want richer information about your directory and its content. In that case, you don’t need to look around for a program other thanls because this command has a full-featured command-line interface with a useful set ofoptions that you can use to customize the command’s behavior.

For example, go ahead and executels with the-l option:

$ls-lsample/total 24-rw-r--r--@ 1 user  staff    83 Aug 17 22:15 hello.txt-rw-r--r--@ 1 user  staff  2609 Aug 17 22:15 lorem.md-rw-r--r--@ 1 user  staff   428 Aug 17 22:15 realpython.md

The output ofls is quite different now. The command displays much more information about the files insample, including permissions, owner, group, date, and size. It also shows the total space that these files use on your computer’s disk.

This richer output results from using the-l option, which is part of the Unixls command-line interface and enables the detailed output format.

Commands, Arguments, Options, Parameters, and Subcommands

Throughout this tutorial, you’ll learn aboutcommands andsubcommands. You’ll also learn about command-linearguments,options, andparameters, so you should incorporate these terms into your tech vocabulary:

• Command: A program or routine that runs at the command line or terminal window. You’ll typically identify a command with the name of the underlying program or routine.

• Argument: A required or optional piece of information that a command uses to perform its intended action. Commands typically accept one or many arguments, which you can provide as a whitespace-separated or comma-separated list on your command line.

• Option, also known asflag orswitch: An optional argument that modifies a command’s behavior. Options are passed to commands using a specific name, like-l in the previous example.

• Parameter: An argument that an option uses to perform its intended operation or action.

• Subcommand: A predefined name that can be passed to an application to run a specific action.

Consider the sample command construct from the previous section:

$ls-lsample/

In this example, you’ve combined the following components of a CLI:

• ls: The command’s name or the app’s name
• -l: An option, switch, or flag that enables detailed outputs
• sample: An argument that provides additional information to the command’s execution

Now consider the following command construct, which showcases the CLI of Python’s package manager, known aspip:

$pipinstall-rrequirements.txt

This is a commonpip command construct, which you’ve probably seen before. It allows you to install the requirements of a given Python project using arequirements.txt file. In this example, you’re using the following CLI components:

• pip: The command’s name
• install: The name of a subcommand ofpip
• -r: An option of theinstall subcommand
• requirements.txt: An argument, specifically a parameter of the-r option

Now you know what command-line interfaces are and what their main parts or components are. It’s time to learn how to create your own CLIs in Python.

Usingsys.argv to Build a Minimal CLI

As an example of usingargv to create a minimal CLI, say that you need to write a small program that lists all the files in a given directory, similar to whatls does. In this situation, you can write something like this:

importsysfrompathlibimportPathif(args_count:=len(sys.argv))>2:print(f"One argument expected, got{args_count-1}")raiseSystemExit(2)elifargs_count<2:print("You must specify the target directory")raiseSystemExit(2)target_dir=Path(sys.argv[1])ifnottarget_dir.is_dir():print("The target directory doesn't exist")raiseSystemExit(1)forentryintarget_dir.iterdir():print(entry.name)

This program implements a minimal CLI by manually processing the arguments provided at the command line, which are automatically stored insys.argv. The first item insys.argv is always the program’s name. The second item will be the target directory. The app shouldn’t accept more than one target directory, so theargs_count must not exceed2.

After checking the content ofsys.argv, you create apathlib.Path object to store the path to your target directory. If this directory doesn’t exist, then you inform the user and exit the app. Thefor loop lists the directory content, one entry per line.

If yourun the script from your command line, then you’ll get the following results:

$pythonls_argv.pysample/hello.txtlorem.mdrealpython.md$pythonls_argv.pyYou must specify the target directory$pythonls_argv.pysample/other_dir/One argument expected, got 2$pythonls_argv.pynon_existing/The target directory doesn't exist

Your program takes a directory as an argument and lists its content. If you run the command without arguments, then you get an error message. If you run the command with more than one target directory, you also get an error. Running the command with a nonexistent directory produces another error message.

Even though your program works okay, parsing command-line arguments manually using thesys.argv attribute isn’t a scalable solution for more complex CLI apps. If your app needs to take many more arguments and options, then parsingsys.argv will be a complex and error-prone task. You need something better, and you get it in Python’sargparse module.

Creating a CLI Withargparse

A much more convenient way to create CLI apps in Python is using theargparse module, which comes in thestandard library. This module was first released inPython 3.2 with PEP389 and is a quick way to create CLI apps in Python without installing a third-party library, such asTyper orClick.

This module was released as a replacement for the oldergetopt andoptparse modules because they lacked some important features.

Python’sargparse module allows you to:

• Parse command-linearguments andoptions
• Take avariable number of parameters in a single option
• Providesubcommands in your CLIs

These features turnargparse into a powerful CLI framework that you can confidently rely on when creating your CLI applications. To use Python’sargparse, you’ll need to follow four straightforward steps:

1. Importargparse.
2. Create anargument parser by instantiatingArgumentParser.
3. Addarguments andoptions to the parser using the.add_argument() method.
4. Call.parse_args() on the parser to get theNamespace of arguments.

As an example, you can useargparse to improve yourls_argv.py script. Go ahead and createls.py with the following code:

importargparsefrompathlibimportPathparser=argparse.ArgumentParser()parser.add_argument("path")args=parser.parse_args()target_dir=Path(args.path)ifnottarget_dir.exists():print("The target directory doesn't exist")raiseSystemExit(1)forentryintarget_dir.iterdir():print(entry.name)

Your code has changed significantly with the introduction ofargparse. The most notable difference from the previous version is that theconditional statements to check the arguments provided by the user are gone. That’s becauseargparse automatically checks the presence of arguments for you.

In this new implementation, you first importargparse and create an argument parser. To create the parser, you use theArgumentParser class. Next, you define an argument calledpath to get the user’s target directory.

The next step is to call.parse_args() to parse the input arguments and get aNamespace object that contains all the user’s arguments. Note that now theargsvariable holds aNamespace object, which has a property for each argument that’s been gathered from the command line.

In this example, you only have one argument, calledpath. TheNamespace object allows you to accesspath using thedot notation onargs. The rest of your code remains the same as in the first implementation.

Now go ahead and run this new script from your command line:

$pythonls.pysample/lorem.mdrealpython.mdhello.txt$pythonls.pyusage: ls.py [-h] pathls.py: error: the following arguments are required: path$pythonls.pysample/other_dir/usage: ls.py [-h] pathls.py: error: unrecognized arguments: other_dir/$pythonls.pynon_existing/The target directory doesn't exist

The first commandprints the same output as your original script,ls_argv.py. In contrast, the second command displays output that’s quite different from inls_argv.py. The program now shows a usage message and issues an error telling you that you must provide thepath argument.

In the third command, you pass two target directories, but the app isn’t prepared for that. Therefore, it shows the usage message again and throws an error letting you know about the underlying problem.

Finally, if you run the script with a nonexistent directory as an argument, then you get an error telling you that the target directory doesn’t exist, so the program can’t do its work.

A new implicit feature is now available to you. Now your program accepts an optional-h flag. Go ahead and give it a try:

$pythonls.py-husage: ls.py [-h] pathpositional arguments:  pathoptions:  -h, --help  show this help message and exit

Great, now your program automatically responds to the-h or--help flag, displaying a help message with usage instructions for you. That’s a really neat feature, and you get it for free by introducingargparse into your code!

With this quick introduction to creating CLI apps in Python, you’re now ready to dive deeper into theargparse module and all its cool features.

Creating a Command-Line Argument Parser

The command-line argument parser is the most important part of anyargparse CLI. All the arguments and options that you provide at the command line will pass through this parser, which will do the hard work for you.

To create a command-line argument parser withargparse, you need to instantiate theArgumentParser class:

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

Theconstructor ofArgumentParser takes many different arguments that you can use to tweak several features of your CLIs. All of its arguments are optional, so the most bare-bones parser that you can create results from instantiatingArgumentParser without any arguments.

You’ll learn more about the arguments to theArgumentParser constructor throughout this tutorial, particularly in the section oncustomizing your argument parser. For now, you can tackle the next step in creating a CLI withargparse. That step is to add arguments and options through the parser object.

Adding Arguments and Options

To add arguments and options to anargparse CLI, you’ll use the.add_argument() method of yourArgumentParser instance. Note that the method is common for arguments and options. Remember that in theargparse terminology, arguments are calledpositional arguments, and options are known asoptional arguments.

The first argument to the.add_argument() method sets the difference between arguments and options. This argument is identified as eithername orflag. So, if you provide aname, then you’ll be defining an argument. In contrast, if you use aflag, then you’ll add an option.

You’ve already worked with command-line arguments inargparse. So, consider the following enhanced version of your customls command, which adds an-l option to the CLI:

 1importargparse 2importdatetime 3frompathlibimportPath 4 5parser=argparse.ArgumentParser() 6 7parser.add_argument("path") 8 9parser.add_argument("-l","--long",action="store_true")1011args=parser.parse_args()1213target_dir=Path(args.path)1415ifnottarget_dir.exists():16print("The target directory doesn't exist")17raiseSystemExit(1)1819defbuild_output(entry,long=False):20iflong:21size=entry.stat().st_size22date=datetime.datetime.fromtimestamp(23entry.stat().st_mtime).strftime(24"%b%d %H:%M:%S"25)26returnf"{size:>6d}{date}{entry.name}"27returnentry.name2829forentryintarget_dir.iterdir():30print(build_output(entry,long=args.long))

In this example, line 9 creates an option with the flags-l and--long. The syntactical difference between arguments and options is that option names start with- for shorthand flags and-- for long flags.

Note that in this specific example, anaction argument set to"store_true" accompanies the-l or--long option, which means that this option will store aBoolean value. If you provide the option at the command line, then its value will beTrue. If you miss the option, then its value will beFalse. You’ll learn more about theaction argument to.add_argument() in theSetting the Action Behind an Option section.

Thebuild_output() function on line 19returns a detailed output whenlong isTrue and a minimal output otherwise. The detailed output will contain the size, modification date, and name of all the entries in the target directory. It uses tools like thePath.stat() and adatetime.datetime object with a customstring format.

Go ahead and execute your program onsample to check how the-l option works:

$pythonls.py-lsample/  2609 Oct 28 14:07:04 lorem.md   428 Oct 28 14:07:04 realpython.md    83 Oct 28 14:07:04 hello.txt

Your new-l option allows you to generate and display a more detailed output about the content of your target directory.

Now that you know how to add command-line arguments and options to your CLIs, it’s time to dive into parsing those arguments and options. That’s what you’ll explore in the following section.

Parsing Command-Line Arguments and Options

Parsing the command-line arguments is another important step in any CLI app based onargparse. Once you’ve parsed the arguments, then you can start taking action in response to their values. In your customls command example, the argument parsing happens on the line containing theargs = parser.parse_args() statement.

This statement calls the.parse_args() method and assigns its return value to theargs variable. The return value of.parse_args() is aNamespace object containing all the arguments and options provided at the command line and their corresponding values.

Consider the following toy example:

>>>fromargparseimportArgumentParser>>>parser=ArgumentParser()>>>parser.add_argument("site")_StoreAction(...)>>>parser.add_argument("-c","--connect",action="store_true")_StoreTrueAction(...)>>>args=parser.parse_args(["Real Python","-c"])>>>argsNamespace(site='Real Python', connect=True)>>>args.site'Real Python'>>>args.connectTrue

TheNamespace object that results from calling.parse_args() on the command-line argument parser gives you access to all the input arguments, options, and their corresponding values by using thedot notation. This way, you can check the list of input arguments and options to take actions in response to the user’s choices at the command line.

You’ll use thisNamespace object in your application’s main code. That’s what you did under thefor loop in your customls command example.

Up to this point, you’ve learned about the main steps for creatingargparse CLIs. Now you can take some time to learn the basics of how to organize and build a CLI application in Python.

Setting Up Your CLI App’s Layout and Build System

Before continuing with yourargparse learning adventure, you should pause and think of how you would organize your code andlay out a CLI project. First, you should observe the following points:

• You can createmodules and packages to organize your code.
• You can name the core package of a Python app after the app itself.
• You’ll name each Python module according to its specific content or functionality.
• You can add a__main__.py module to any Python package if you want to make that package directly executable.

With these ideas in mind and considering that themodel-view-controller (MVC) pattern is an effective way to structure your applications, you can use the following directory structure when laying out a CLI project:

hello_cli/│├── hello_cli/│   ├── __init__.py│   ├── __main__.py│   ├── cli.py│   └── model.py│├── tests/│   ├── __init__.py│   ├── test_cli.py│   └── test_model.py│├── pyproject.toml├── README.md└── requirements.txt

Thehello_cli/ directory is the project’s root directory. There, you’ll place the following files:

• pyproject.toml is aTOML file that specifies the project’sbuild system and otherconfigurations.
• README.md provides the projectdescription andinstructions for installing and running the application. Adding a descriptive and detailedREADME.md file to your projects is a best practice in programming, especially if you’re planning to release the project as an open-source solution.
• requirements.txt provides a conventional file that lists the project’sexternal dependencies. You’ll use this file to automatically install the dependencies usingpip with the-r option.

Then you have thehello_cli/ directory that holds the app’s core package, which contains the following modules:

• __init__.py enableshello_cli/ as a Pythonpackage.
• __main__.py provides the application’sentry-point script or executable file.
• cli.py provides the application’s command-line interface. The code in this file will play theview-controller role in the MVC-based architecture.
• model.py contains the code that supports the app’s main functionalities. This code will play themodel role in your MVC layout.

You’ll also have atests/ package containing files withunit tests for your app’s components. In this specific project layout example, you havetest_cli.py for unit tests that check the CLI’s functionality andtest_model.py for unit tests that check your model’s code.

Thepyproject.toml file allows you to define the app’s build system as well as many other general configurations. Here’s a minimal example of how to fill in this file for your samplehello_cli project:

# pyproject.toml[build-system]requires=["setuptools>=64.0.0","wheel"]build-backend="setuptools.build_meta"[project]name="hello_cli"version="0.0.1"description="My awesome Hello CLI application"readme="README.md"authors=[{name="Real Python",email="info@realpython.com"}][project.scripts]hello_cli="hello_cli.__main__:main"

The[build-system]table header sets upsetuptools as your app’sbuild system and specifies which dependencies Python needs to install for building your app. The[project] header provides general metadata for your application. This metadata is pretty useful when you want topublish your app to the Python package index (PyPI). Finally, the[project.scripts] heading defines the entry point to your application.

With this quick dive into laying out and building CLI projects, you’re ready to continue learning aboutargparse, especially how to customize your command-line argument parser.

Tweaking the Program’s Help and Usage Content

Providing usage instructions and help to the users of your CLI applications is a best practice that’ll make your users’ lives more pleasant with a greatuser experience (UX). In this section, you’ll learn how to take advantage of some arguments ofArgumentParser to fine-tune how your CLI apps show help and usage messages to their users. You’ll learn how to:

• Set the program’s name
• Define the program’s description and epilog message
• Display grouped help for arguments and options

To kick things off, you’ll start by setting your program’s name and specifying how that name will look in the context of a help or usage message.

$pythonls.py-husage: ls.py [-h] [-l] pathpositional arguments:  pathoptions:  -h, --help  show this help message and exit  -l, --long

importargparseimportdatetimefrompathlibimportPathparser=argparse.ArgumentParser(prog="ls")# ...forentryintarget_dir.iterdir():print(build_output(entry,long=args.long))

$pythonls.py-husage: ls [-h] [-l] pathpositional arguments:  pathoptions:  -h, --help  show this help message and exit  -l, --long

importargparseimportdatetimefrompathlibimportPathparser=argparse.ArgumentParser(prog="ls",description="List the content of a directory",epilog="Thanks for using%(prog)s! :)",)# ...forentryintarget_dir.iterdir():print(build_output(entry,long=args.long))

$pythonls.py-husage: ls [-h] [-l] pathList the content of a directorypositional arguments:  pathoptions:  -h, --help  show this help message and exit  -l, --longThanks for using ls! :)

# ...parser=argparse.ArgumentParser(prog="ls",description="List the content of a directory",epilog="Thanks for using%(prog)s! :)",)general=parser.add_argument_group("general output")general.add_argument("path")detailed=parser.add_argument_group("detailed output")detailed.add_argument("-l","--long",action="store_true")args=parser.parse_args()# ...forentryintarget_dir.iterdir():print(build_output(entry,long=args.long))

$pythonls.py-husage: ls [-h] [-l] pathList the content of a directoryoptions:  -h, --help  show this help message and exitgeneral output:  pathdetailed output:  -l, --longThanks for using ls! :)

Providing Global Settings for Arguments and Options

Beyond customizing the usage and help messages,ArgumentParser also allows you to perform a few other interesting tweaks to your CLI apps. Some of these tweaks include:

• Defining a global default value for arguments and options
• Loading arguments and options from an external file
• Allowing or disallowing option abbreviations

Sometimes, you may need to specify a singleglobal default value for your app’s arguments and options. You can do this by passing the default value toargument_default on the call to theArgumentParser constructor.

This feature may be only rarely useful because arguments and options often have a different data type or meaning, and it can be difficult to find a value that suits all the requirements.

However, a common use case ofargument_default is when you want to avoid adding arguments and options to theNamespace object. In this situation, you can use theSUPPRESSconstant as the default value. This default value will make it so that only the arguments and options provided at the command line end up stored in the argumentsNamespace.

As an example, go ahead and modify your customls command as in the snippet below:

importargparseimportdatetimefrompathlibimportPathparser=argparse.ArgumentParser(prog="ls",description="List the content of a directory",epilog="Thanks for using%(prog)s! :)",argument_default=argparse.SUPPRESS,)# ...forentryintarget_dir.iterdir():try:long=args.longexceptAttributeError:long=Falseprint(build_output(entry,long=long))

By passingSUPPRESS to theArgumentParser constructor, you prevent non-supplied arguments from being stored in the argumentsNamespace object. That’s why you have to check if the-l or--long option was actually passed before callingbuild_output(). Otherwise, your code will break with anAttributeError becauselong won’t be present inargs.

Another cool feature ofArgumentParser is that it allows you toload argument values from an external file. This possibility comes in handy when you have an application with long or complicated command-line constructs, and you want to automate the process of loading argument values.

In this situation, you can store the argument values in an external file and ask your program to load them from it. To try this feature out, go ahead and create the following toy CLI app:

importargparseparser=argparse.ArgumentParser(fromfile_prefix_chars="@")parser.add_argument("one")parser.add_argument("two")parser.add_argument("three")args=parser.parse_args()print(args)

Here, you pass the@ symbol to thefromfile_prefix_chars argument ofArgumentParser. Then you create three required arguments that must be provided at the command line.

Now say that you often use this application with the same set of argument values. To facilitate and streamline your work, you can create a file containing appropriate values for all the necessary arguments, one per line, like in the followingargs.txt file:

firstsecondthird

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

$pythonfromfile.py@args.txtNamespace(one='first', two='second', three='third')

In this command’s output, you can see thatargparse has read the content ofargs.txt and sequentially assigned values to each argument of yourfromfile.py program. All the arguments and their values are successfully stored in theNamespace object.

The ability to acceptabbreviated option names is another cool feature ofargparse CLIs. This feature is enabled by default and comes in handy when your program has long option names. As an example, consider the following program, which prints out the value that you specify at the command line under the--argument-with-a-long-name option:

importargparseparser=argparse.ArgumentParser()parser.add_argument("--argument-with-a-long-name")args=parser.parse_args()print(args.argument_with_a_long_name)

This program prints whatever your pass as an argument to the--argument-with-a-long-name option. Go ahead and run the following commands to check how the Pythonargparse module handles abbreviations for you:

$pythonabbreviate.py--argument-with-a-long-name4242$pythonabbreviate.py--argument4242$pythonabbreviate.py--a4242

These examples show how you can abbreviate the name of the--argument-with-a-long-name option and still get the app to work correctly. This feature is enabled by default. If you want to disable it and forbid abbreviations, then you can use theallow_abbrev argument toArgumentParser:

importargparseparser=argparse.ArgumentParser(allow_abbrev=False)parser.add_argument("--argument-with-a-long-name")args=parser.parse_args()print(args.argument_with_a_long_name)

Settingallow_abbrev toFalse disables abbreviations in command-line options. From this point on, you’ll have to provide the complete option name for the program to work correctly. Otherwise, you’ll get an error:

$pythonabbreviate.py--argument-with-a-long-name4242$pythonabbreviate.py--argument42usage: abbreviate.py [-h] [--argument-with-a-long-name ...]abbreviate.py: error: unrecognized arguments: --argument 42

The error message in the second example tells you that the--argument option isn’t recognized as a valid option. To use the option, you need to provide its full name.

Setting the Action Behind an Option

When you add an option or flag to a command-line interface, you’ll often need to define how you want to store the option’s value in theNamespace object that results from calling.parse_args(). To do this, you’ll use theaction argument to.add_argument(). Theaction argument defaults to"store", which means that the value provided for the option at hand will be stored as is in theNamespace.

Theaction argument can take one of several possible values. Here’s the list of these possible values and their meanings:

In this table, the values that include the_const suffix in their names require you to provide the desired constant value using theconst argument in the call to the.add_argument() method. Similarly, theversion action requires you to provide the app’s version by passing theversion argument to.add_argument(). You should also note that only thestore andappend actions can and must take arguments at the command line.

To try these actions out, you can create a toy app with the following implementation:

importargparseparser=argparse.ArgumentParser()parser.add_argument("--name",action="store")# Equivalent to parser.add_argument("--name")parser.add_argument("--pi",action="store_const",const=3.14)parser.add_argument("--is-valid",action="store_true")parser.add_argument("--is-invalid",action="store_false")parser.add_argument("--item",action="append")parser.add_argument("--repeated",action="append_const",const=42)parser.add_argument("--add-one",action="count")parser.add_argument("--version",action="version",version="%(prog)s 0.1.0")args=parser.parse_args()print(args)

This program implements an option for each type ofaction discussed above. Then the program prints the resultingNamespace of arguments. Here’s a summary of how these options will work:

• --name will store the value passed, without any further consideration.

• --pi will automatically store the target constant when the option is provided.

• --is-valid will storeTrue when provided andFalse otherwise. If you need the opposite behavior, use astore_false action like--is-invalid in this example.

• --item will let you create a list of all the values. You must repeat the option for each value. Under the hood,argparse will append the items to a list named after the option itself.

• --repeated will work similarly to--item. However, it always appends the same constant value, which you must provide using theconst argument.

• --add-one counts how many times the option is passed at the command line. This type of option is quite useful when you want to implement several verbosity levels in your programs. For example,-v can mean level one of verbosity,-vv may indicate level two, and so on.

• --version shows the app’s version and terminates the execution immediately. Note that you must provide the version number beforehand, which you can do by using theversion argument when creating the option with.add_argument().

Go ahead and run the script with the following command construct to try out all these options:

• Windows
• Linux + macOS

PS>pythonactions.py`>--namePython`>--pi`>--is-valid`>--is-invalid`>--item1--item2--item3`>--repeat--repeat--repeat`>--add-one--add-one--add-oneNamespace(    name='Python',    pi=3.14,    is_valid=True,    is_invalid=False,    item=['1', '2', '3'],    repeated=[42, 42, 42],    add_one=3)PS>pythonactions.py--versionactions.py 0.1.0

$pythonactions.py\--namePython\--pi\--is-valid\--is-invalid\--item1--item2--item3\--repeat--repeat--repeat\--add-one--add-one--add-oneNamespace(    name='Python',    pi=3.14,    is_valid=True,    is_invalid=False,    item=['1', '2', '3'],    repeated=[42, 42, 42],    add_one=3)$pythonactions.py--versionactions.py 0.1.0

With this command, you show how all the actions work and how they’re stored in the resultingNamespace object. Theversion action is the last one that you used, because this option just shows the version of the program and then ends the execution. It doesn’t get stored in theNamespace object.

Even though the default set of actions is quite complete, you also have the possibility of creating custom actions by subclassing theargparse.Action class. If you decide to do this, then you must override the.__call__() method, which turnsinstances into callable objects. Optionally, you can override the.__init__() and.format_usage() methods depending on your needs.

To override the.__call__() method, you need to ensure that the method’s signature includes theparser,namespace,values, andoption_string arguments.

In the following example, you implement a minimal and verbosestore action that you can use when building your CLI apps:

importargparseclassVerboseStore(argparse.Action):def__call__(self,parser,namespace,values,option_string=None):print(f"Storing{values} in the{option_string} option...")setattr(namespace,self.dest,values)parser=argparse.ArgumentParser()parser.add_argument("-n","--name",action=VerboseStore)args=parser.parse_args()print(args)

In this example, you defineVerboseStore inheriting fromargparse.Action. Then you override the.__call__() method to print an informative message and set the target option in the namespace of command-line arguments. Finally, the app prints the namespace itself.

Go ahead and run the following command to try out your custom action:

$pythoncustom_action.py--namePythonStoring Python in the --name option...Namespace(name='Python')

Great! Your program now prints out a message before storing the value provided to the--name option at the command line. Custom actions like the one in the above example allow you to fine-tune how your programs’ options are stored.

To continue fine-tuning yourargparse CLIs, you’ll learn how to customize the input value of command-line arguments and options in the following section.

Customizing Input Values in Arguments and Options

Another common requirement when you’re building CLI applications is to customize the input values that arguments and options will accept at the command line. For example, you may require that a given argument accept an integer value, a list of values, a string, and so on.

By default, any argument provided at the command line will be treated as a string. Fortunately,argparse has internal mechanisms to check if a given argument is a valid integer, string, list, and more.

In this section, you’ll learn how to customize the way in whichargparse processes and stores input values. Specifically, you’ll learn how to:

• Set thedata type of input values for arguments and options
• Takemultiple input values in arguments and options
• Providedefault values for arguments and options
• Define a list ofallowed input values for arguments and options

To kick things off, you’ll start by customizing the data type that your arguments and options will accept at the command line.

importargparseparser=argparse.ArgumentParser()parser.add_argument("--dividend",type=int)parser.add_argument("--divisor",type=int)args=parser.parse_args()print(args.dividend/args.divisor)

$pythondivide.py--dividend42--divisor221.0$pythondivide.py--dividend"42"--divisor"2"21.0$pythondivide.py--dividend42--divisor2.0usage: divide.py [-h] [--dividend DIVIDEND] [--divisor DIVISOR]divide.py: error: argument --divisor: invalid int value: '2.0'$pythondivide.py--dividend42--divisortwousage: divide.py [-h] [--dividend DIVIDEND] [--divisor DIVISOR]divide.py: error: argument --divisor: invalid int value: 'two'

importargparseparser=argparse.ArgumentParser()parser.add_argument("--coordinates",nargs=2)args=parser.parse_args()print(args)

$pythonpoint.py--coordinates23Namespace(coordinates=['2', '3'])$pythonpoint.py--coordinates2usage: point.py [-h] [--coordinates COORDINATES COORDINATES]point.py: error: argument --coordinates: expected 2 arguments$pythonpoint.py--coordinates234usage: point.py [-h] [--coordinates COORDINATES COORDINATES]point.py: error: unrecognized arguments: 4$pythonpoint.py--coordinatesusage: point.py [-h] [--coordinates COORDINATES COORDINATES]point.py: error: argument --coordinates: expected 2 arguments

importargparseparser=argparse.ArgumentParser()parser.add_argument("numbers",nargs="*",type=float)args=parser.parse_args()print(sum(args.numbers))

$pythonsum.py1236.0$pythonsum.py12345621.0$pythonsum.py0

importargparseparser=argparse.ArgumentParser()parser.add_argument("files",nargs="+")args=parser.parse_args()print(args)

$pythonfiles.pyhello.txtNamespace(files=['hello.txt'])$pythonfiles.pyhello.txtrealpython.mdREADME.mdNamespace(files=['hello.txt', 'realpython.md', 'README.md'])$pythonfiles.pyusage: files.py [-h] files [files ...]files.py: error: the following arguments are required: files

importargparseparser=argparse.ArgumentParser()parser.add_argument("veggies",nargs="+")parser.add_argument("fruits",nargs="*")args=parser.parse_args()print(args)

$pythoncooking.pypeppertomatoapplebananaNamespace(veggies=['pepper', 'tomato', 'apple', 'banana'], fruits=[])

importargparseparser=argparse.ArgumentParser()parser.add_argument("--veggies",nargs="+")parser.add_argument("--fruits",nargs="*")args=parser.parse_args()print(args)

$pythoncooking.py--veggiespeppertomato--fruitsapplebananaNamespace(veggies=['pepper', 'tomato'], fruits=['apple', 'banana'])

importargparseimportdatetimefrompathlibimportPath# ...general=parser.add_argument_group("general output")general.add_argument("path",nargs="?",default=".")# ...

$cdsample/$python../ls.pylorem.mdrealpython.mdhello.txt

importargparseparser=argparse.ArgumentParser()parser.add_argument("--size",choices=["S","M","L","XL"],default="M")args=parser.parse_args()print(args)

$pythonsize.py--sizeSNamespace(size='S')$pythonchoices.py--sizeAusage: choices.py [-h] [--size {S,M,L,XL}]choices.py: error: argument --size: invalid choice: 'A'    (choose from 'S', 'M', 'L', 'XL')

importargparsemy_parser=argparse.ArgumentParser()my_parser.add_argument("--weekday",type=int,choices=range(1,8))args=my_parser.parse_args()print(args)

$pythondays.py--weekday2Namespace(weekday=2)$pythondays.py--weekday6Namespace(weekday=6)$pythondays.py--weekday9usage: days.py [-h] [--weekday {1,2,3,4,5,6,7}]days.py: error: argument --weekday: invalid choice: 9    (choose from 1, 2, 3, 4, 5, 6, 7)

Providing and Customizing Help Messages in Arguments and Options

As you already know, a great feature ofargparse is that it generates automatic usage and help messages for your applications. You can access these messages using the-h or--help flag, which is included by default in anyargparse CLI.

Up to this point, you’ve learned how to provide description and epilog messages for your apps. In this section, you’ll continue improving your app’s help and usage messages by providing enhanced messages for individual command-line arguments and options. To do this, you’ll use thehelp andmetavar arguments of.add_argument().

Go back to your customls command and run the script with the-h switch to check its current output:

$pythonls.py-husage: ls [-h] [-l] [path]List the content of a directoryoptions:  -h, --help  show this help message and exitgeneral output:  pathdetailed output:  -l, --longThanks for using ls! :)

This output looks nice, and it’s a good example of howargparse saves you a lot of work by providing usage and help message out of the box.

Note that only the-h or--help option shows a descriptive help message. In contrast, your own argumentspath and-l or--long don’t show a help message. To fix that, you can use thehelp argument.

Open yourls.py and update it like in the following code:

importargparseimportdatetimefrompathlibimportPath# ...general=parser.add_argument_group("general output")general.add_argument("path",nargs="?",default=".",help="take the path to the target directory (default:%(default)s)",)detailed=parser.add_argument_group("detailed output")detailed.add_argument("-l","--long",action="store_true",help="display detailed directory content",)# ...

In this update tols.py, you use thehelp argument of.add_argument() to provide specific help messages for your arguments and options.

Now go ahead and run the app with the-h flag again:

$pythonls.py-husage: ls [-h] [-l] [path]List the content of a directoryoptions:  -h, --help  show this help message and exitgeneral output:  path        take the path to the target directory (default: .)detailed output:  -l, --long  display detailed directory contentThanks for using ls! :)

Now bothpath and-l show descriptive help messages when you run the app with the-h flag. Note thatpath includes its default value in its help message, which provides valuable information to your users.

Another desired feature is to have a nice and readable usage message in your CLI apps. The default usage message ofargparse is pretty good already. However, you can use themetavar argument of.add_argument() to slightly improve it.

Themetavar argument comes in handy when a command-line argument or option accepts input values. It allows you to give this input value a descriptive name that the parser can use to generate the help message.

As an example of when to usemetavar, go back to yourpoint.py example:

importargparseparser=argparse.ArgumentParser()parser.add_argument("--coordinates",nargs=2)args=parser.parse_args()print(args)

If you run this application from your command line with the-h switch, then you get an output that’ll look like the following:

$pythonpoint.py-husage: point.py [-h] [--coordinates COORDINATES COORDINATES]options:  -h, --help            show this help message and exit  --coordinates COORDINATES COORDINATES

By default,argparse uses the original name of command-line options to designate their corresponding input values in the usage and help messages, as you can see in the highlighted lines. In this specific example, the nameCOORDINATES in the plural may be confusing. Should your users provide the point’s coordinates two times?

You can remove this ambiguity by using themetavar argument:

importargparseparser=argparse.ArgumentParser()parser.add_argument("--coordinates",nargs=2,metavar=("X","Y"),help="take the Cartesian coordinates%(metavar)s",)args=parser.parse_args()print(args)

In this example, you use a tuple as the value tometavar. The tuple contains the two coordinate names that people commonly use to designate a pair of Cartesian coordinates. You also provide a custom help message for--coordinates, including a format specifier with themetavar argument.

If you run the script with the-h flag, then you get the following output:

$pythoncoordinates.py-husage: coordinates.py [-h] [--coordinates X Y]options:  -h, --help         show this help message and exit  --coordinates X Y  take the Cartesian coordinates ('X', 'Y')

Now your app’s usage and help messages are way clearer than before. Now your users will immediately know that they need to provide two numeric values,X andY, for the--coordinates option to work correctly.