Skip to content
CodeMDD.io | Coding Tutorials

Working with argparse in Python

[

Build Command-Line Interfaces With Python’s argparse

Getting to Know Command-Line Interfaces

  • Command-Line Interfaces (CLIs)
  • Commands, Arguments, Options, Parameters, and Subcommands

Getting Started With CLIs in Python: sys.argv vs argparse

  • Using sys.argv to Build a Minimal CLI
  • Creating a CLI With argparse

To create a minimal Command-Line Interface (CLI) in Python, you can use the sys.argv module. Here’s an example:

import sys


if __name__ == "__main__":
    if len(sys.argv) > 1:
        print(f"Hello, {sys.argv[1]}!")
    else:
        print("Hello, World!")

In this example, the sys.argv module is used to access the arguments passed to the script via the command line. By checking the length of sys.argv, we can determine if any arguments were provided. If an argument is provided, the script will print a personalized greeting. Otherwise, it will print a generic greeting.

However, as your CLI becomes more complex and you need to handle different types of arguments and options, it becomes necessary to use a more powerful tool like the argparse module. The argparse module provides a more robust and flexible way to create CLIs in Python.

To create a CLI with argparse, you need to define a ArgumentParser object and add arguments and options to it. Here’s an example:

import argparse


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="A command-line app")


    parser.add_argument("name", help="Your name")
    parser.add_argument("--greeting", help="Specify a greeting")


    args = parser.parse_args()


    if args.greeting:
        print(f"{args.greeting}, {args.name}!")
    else:
        print(f"Hello, {args.name}!")

In this example, a ArgumentParser object is created with a description of the app. Then, two arguments are added to the ArgumentParser object: name and greeting. The name argument is a required positional argument, while the greeting argument is an optional argument specified with the --greeting flag.

The args object is obtained by calling parser.parse_args(), which parses the command-line arguments and returns an object containing the values of the provided arguments.

Finally, depending on the presence of the --greeting option, the script prints the appropriate greeting.

Creating Command-Line Interfaces With Python’s argparse

  • Creating a Command-Line Argument Parser
  • Adding Arguments and Options
  • Parsing Command-Line Arguments and Options
  • Setting Up Your CLI App’s Layout and Build System

To create a command-line argument parser with argparse, you need to initialize an ArgumentParser object. Here’s an example:

import argparse


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="A command-line app")

The ArgumentParser object is initialized with a description of the app, which will be displayed when the user asks for help or when an error occurs.

To add arguments and options to the ArgumentParser object, you can use the add_argument method. Here’s an example:

parser.add_argument("name", help="Your name")
parser.add_argument("--greeting", "-g", help="Specify a greeting")

In this example, the add_argument method is used to add a positional argument called name and an optional argument called greeting. The name argument is a required argument, while the greeting argument is optional and can be specified using either the --greeting or -g flag.

After adding the necessary arguments and options, you can parse the command-line arguments by calling the parse_args method of the ArgumentParser object. Here’s an example:

args = parser.parse_args()

The args object will contain the values of the provided arguments and options.

Finally, you can access the values of the arguments and options and perform the desired actions in your CLI.

Customizing Your Command-Line Argument Parser

  • Tweaking the Program’s Help and Usage Content
  • Providing Global Settings for Arguments and Options

You can tweak the help and usage content of your CLI by customizing the ArgumentParser object.

To set a custom program name, you can use the prog parameter of the ArgumentParser object. Here’s an example:

parser = argparse.ArgumentParser(prog="myapp", description="A command-line app")

In this example, the program name will be displayed as myapp. By default, the program name is obtained from sys.argv[0].

To change the help message for a specific argument or option, you can use the help parameter of the add_argument method. Here’s an example:

parser.add_argument("--greeting", "-g", help="Specify a custom greeting")

In this example, the help message for the --greeting option will be displayed as “Specify a custom greeting”.

You can also provide global settings for all the arguments and options in your CLI. For example, you can change the format of the ‘usage’ string by setting the usage parameter of the ArgumentParser object. Here’s an example:

parser = argparse.ArgumentParser(usage="%(prog)s [options] name")

In this example, the ‘usage’ string will be displayed as “<program_name> [options] name”. By default, the ‘usage’ string is generated automatically based on the defined arguments and options.

Fine-Tuning Your Command-Line Arguments and Options

  • Setting the Action Behind an Option
  • Customizing Input Values in Arguments and Options
  • Providing and Customizing Help Messages in Arguments and Options

You can fine-tune your command-line arguments and options by specifying different actions, customizing input values, and providing custom help messages.

To set the action behind an option, you can use the action parameter of the add_argument method. The action determines what happens when the option is detected in the command line. Here are some commonly used actions:

  • "store": Stores the value specified in the option.
  • "store_true": Stores True if the option is present, otherwise stores False.
  • "store_false": Stores False if the option is present, otherwise stores True.

To customize input values in arguments and options, you can use the type parameter of the add_argument method. The type parameter specifies a callable that is used to convert the input value to the desired type. Here’s an example:

parser.add_argument("count", type=int, help="Specify an integer count")

In this example, the count argument will be converted to an integer.

To provide and customize help messages in arguments and options, you can use the help parameter of the add_argument method. The help parameter specifies the help message that will be displayed when the user asks for help. Here’s an example:

parser.add_argument("name", help="Your name")

In this example, the help message for the name argument will be displayed as “Your name”.

Defining Mutually Exclusive Argument and Option Groups

You can define mutually exclusive argument and option groups using the add_mutually_exclusive_group method of the ArgumentParser object. This allows you to specify that only one argument or option from the group can be present at a time.

Here’s an example:

group = parser.add_mutually_exclusive_group()
group.add_argument("--goodbye", "-g", help="Specify a farewell")
group.add_argument("--farewell", help="Specify a goodbye")

In this example, the --goodbye and --farewell options are in a mutually exclusive group. This means that if the user includes both options in the command line, an error will be raised. Only one of the options can be present at a time.

Adding Subcommands to Your CLIs

You can add subcommands to your CLIs using the add_subparsers method of the ArgumentParser object. This allows you to create a CLI with different commands that perform specific actions.

Here’s an example:

subparsers = parser.add_subparsers(title="commands", dest="command")


subparser1 = subparsers.add_parser("command1", help="Perform command 1")
subparser1.add_argument("arg1", help="Argument 1")


subparser2 = subparsers.add_parser("command2", help="Perform command 2")
subparser2.add_argument("arg2", help="Argument 2")

In this example, two subcommands, command1 and command2, are added to the CLI. Each subcommand can have its own set of arguments and options.

Handling How Your CLI App’s Execution Terminates

You can customize how your CLI app’s execution terminates by handling different types of exceptions and errors.

For example, you can handle the SystemExit exception to perform custom actions when the user requests help or when an error occurs.

try:
    args = parser.parse_args()
except SystemExit:
    # Perform custom actions when the user requests help or an error occurs

You can also handle specific exceptions raised by your app’s logic to display custom error messages or perform specific actions.

Conclusion

In this tutorial, you learned how to build command-line interfaces with Python’s argparse module. You explored the basics of command-line interfaces, the differences between sys.argv and argparse, and the steps to create, customize, and fine-tune your CLIs. With argparse, you can create powerful and user-friendly command-line applications that enhance your Python projects.