Next / Previous / Contents / Shipman's homepage

28.10. argparse: Processing command line arguments

This module is the current recommended standard module for processing arguments from the command line. The module has many more features than those described here: refer to the full documentation.

28.10.1. Types of command line arguments

For the purposes of this module, arguments are divided into two types:

  • Positional arguments do not begin with a hyphen. When there are multiple positional arguments, the meaning of each one is inferred from their position relative to the other positional arguments.

  • Optional arguments begin with a hyphen. In general each optional argument may have two forms, a short form consisting of a hyphen and a letter (e.g., “-h” for help), and a long form consisting of two hyphens and a full name (e.g., “--help”). Generally optional arguments are not required, but your program can make them required if you wish.

    Some optional arguments may allow or require a value. For example, let's suppose your script has an option that specifies the name of a river, and that the short form is “-r” and the long form is “--river”. On the command line, the user can specify the Nile in any of these four ways:

    -r Nile
    -rNile
    --river Nile
    --river=Nile
    

    Users may group multiple short-form options together. For example, if a script named sss has options “-a”, “-m”, “-p”, and “-s”, these two examples are valid and equivalent:

    sss -a -m -p -s
    sss -spma
    

    A short-form option that takes an argument may occur as part of such a group, but only if it is the last option in the group.

    Contrary to Unix practice, optional arguments may occur anywhere relative to the positional arguments. Also, the names of long-form optional arguments may be abbreviated if the abbreviation is unambiguous. For example, if a script has two long-form options --pratt and --polonius, option --pr will be accepted as an abbreviation for --pratt; but --p would not be acceptable because it is ambiguous.

28.10.2. Overall flow of argument processing

Here is the general procedure for using the argparse module to check and process your command line arguments, which in most cases will come from sys.argv (see Section 28.6, “sys: Universal system interface”).

  1. Create an argparse.ArgumentParser instance. See Section 28.10.3, “The ArgumentParser() constructor”.

  2. For each command line argument, call the .add_argument() method of that instance once to define what that argument may be. See Section 28.10.4, “The ArgumentParser.add_argument() method”.

  3. Call the .parse_args() method of the instance. If there are any errors in the command line, this method will print a message summarizing the arguments, and then terminate execution.

    If the arguments are correct according to the rules that you have specified, all the values will be packaged into an object containing all your arguments as attributes, with default values filled in where necessary. See Section 28.10.5, “The ArgumentParser.parse_args() method”.

28.10.3. The ArgumentParser() constructor

Here is the calling sequence to create an ArgumentParser instance P:

import argparse

P = argparse.ArgumentParser(**kw)

Valid keyword arguments include:

description

A string describing the overall purpose of your script. This string will be displayed in the generated help message.

add_help=True

By default, the returned parser will implement options -h and --help to display the help message showing the valid option syntax. Use add_help=False if you don't want this behavior.

prog

By default, when the name of your script is displayed, it will be the name from sys.argv[0]. If you would like to display a different program name, pass that name as the value of this keyword argument.

Here's an example.

parser = argparse.ArgumentParser(prog="nile-source",
              description="Find the source of the Nile")

28.10.4. The ArgumentParser.add_argument() method

To define each command line argument, call the .add_argument() method of an ArgumentParser instance P. There are two forms, depending on whether you are defining a positional command line argument or an optional argument. In either case, there are a number of keyword arguments denoted as “**kw”; we will describe these arguments below.

To define a positional command line argument, use this form:

P.add_argument(posName, **kw)

The posName is a string that specifies the name of the argument (which cannot begin with “-”). For example, if your ArgumentParser instance is p, to define a positional argument called “inFile”, your call might begin like this:

p.add_argument("inFile", ...)

To define an optional command line argument, use this form:

P.add_argument(s0, s1, ..., , **kw)

Each si is a string defining the option name, starting with either "-" for short-form options or "--" for options with the long form.

For example, if you have an option whose short form is “-x” and whose long form is “--exec”, your method call would begin:

p.add_argument("-x", "--exec", ...)

You can specify any number of short and long form options in this way.

Here are the principle keyword arguments to the .add_argument() method. Some of these require information to be passed through other keyword arguments.

dest

Name of the attribute where the value of this argument will be stored in the result returned by the ArgumentParser.parse_args() method. If you don't specify this, the attribute name will be:

  • For positional arguments, the attribute name will be the name passed as the first argument to .add_argument().

  • For optional arguments, the attribute name is the first long-form option name given if there is at least one; otherwise the attribute name is the first short-form option name given.

    For example, if the method call looks like .add_argument('-x', '--exec', '--run', ...), the value will be stored in the .exec attribute of the result returned by .arg_parse().

action

Specifies what happens when this command line argument is processed. The value must be one of the following:

action='store'

Store the argument value as a string in the result returned by .arg_parse(). The name of the attribute where it is stored is given by the dest keyword argument, or the default name as explained above.

action='store_const'

You must provide a keyword argument const=V, where V is the value to be stored in the result returned from .arg_parse().

action='store_true'

Store a True value in the returned result. If the user does not supply this option, .parse_args() stores a False value in the returned result.

action='store_false'

Store a False value in the returned result. If the user doesn't supply this option, .parse_args() stores a True value in the returned result.

action='append'

For arguments that may be repeated, this action causes each repeated argument to be appended to the list of values in the result returned by .arg_parse() .

action='append_const'

This works like action='append', but the value V, specified elsewhere by const=V is appended to the list of arguments.

action='version'

This option instructs the ArgumentParser instance to implement a --version option that reports the current version of your script. You must provide a version=V argument that defines the version string as V.

If you don't supply an action argument, the default is action=None. In this case:

  • For positional command line arguments, the value of the argument is stored.

  • For optional command line arguments, the stored value is None, unless you provide a default=S argument to .add_argument().

nargs

Specifies the number of this kind of argument. This feature works for both positional and optional arguments. In the value returned by .parse_args(), the attribute associated with this argument will be a list, not a single value.

  • If the value of the nargs option is an integer, exactly that many arguments must be provided. The corresponding attribute will be set to a list of the provided values.

  • nargs='*' means zero or more. For positional arguments, this means all the remaining arguments supplied will be included in the returned list of values.

  • nargs='+' means one or more: there must be at least one such argument, but there may be any number.

  • nargs='?' means that this argument is optional.

    • For positional command line arguments, the returned value will be the value from the command line if there is one; otherwise you will supply the default returned value D by providing keyword argument default=D to the .add_argument() call.

    • For optional command line arguments, nargs='?' signifies that the option may be given a value.

      • If the user does not provide this option, the value returned by .arg_parse() will be the default value from the const=C argument to .add_argument().

      • If the user provides this option but does not follow it with a value, the value returned by .arg_parse() will be the default value from the default=D argument to .add_argument().

      • If the user provides this option with a value V, the attribute of the value returned by .arg_parse() will be V.

  • The default value is nargs=None. In this case:

    • For a positional command line argument, this means exactly one is expected.

      The corresponding attribute will be set to a single value. Compare nargs=1, which sets that attribute to a list containing a single value.

    • For an optional command line argument, the stored value is None unless you provide a default value D with default=D.

const

See above under action='store_const' and action='append_const'.

default

Provides a default value; see above under nargs.

type

Convert the value to a given type. For example, type=int would attempt to convert the associated argument to a Python int; if the argument is not a valid integer, .arg_parse() will print the usage message and terminate.

For arguments that are file names, the argparse module will even open the file for you. Here is the general form:

type=argparse.FileType(mode=M)

where M is the mode string as in the second argument to open(). For example, this form would attempt to open a new file for writing, using the value of the command line option as the file name.

p.add_argument(..., type=argparse.FileType(mode='w'), ...)

Note that .arg_parse() may raise an IOError or OSError exception if the file can't be opened.

You can specify any converter function as the value of the type keyword argument. This function takes one argument, a string, and returns a value of whatever type you like. Your converter function may also raise an argparse.ArgumentTypeError exception to signify an invalid value.

choices

An iterable that specifies the only valid choices. For example, choices=('red', 'grn', 'blu') would allow only those three specific strings as values of the associated command line argument.

required

If an argument that starts with a hyphen is not actually optional, use required=True.

help

A string describing what this option does. Strongly recommended, and it will be displayed in the help message.

metavar

Specifies the name of this optional for external display. For example, suppose your .add_argument() call starts like this:

P.add_argument('inFile', metavar='INFILE', ...)

Then the argument value will be stored in attribute .inFile of the result returned by .arg_parse(), but the help message will refer to this argument as “INFILE”.

28.10.5. The ArgumentParser.parse_args() method

Once you have added all your command line arguments, the call to the .parse_args() method looks like this, where P is your ArgumentParser instance.

P.parse_args(args=None, namespace=None)

The args parameter specifies a set of command line arguments as a list of strings. If you omit this, the command line arguments will be taken from sys.argv.

By default, the returned value will be an instance of class argparse.Namespace. The values returned by parsing the command line will be stored as attributes in this instance. However, you may instead use namespace to specify some instance to which the attributes will be added.

Here's an extended example. This script sets up four command line arguments and then tests it against various simulated argument lists.

#!/usr/bin/env python
from __future__ import print_function
import sys
import argparse

def test(p, argList):
    print("\n=== Test with", argList)
    r = p.parse_args(args=argList)
    print(vars(r))

p = argparse.ArgumentParser(prog='larch',
                            description="Number 1: The Larch")
p.add_argument('-n', '--name', default='Dinsdale',
               help='Name your amoeba')
p.add_argument('-x', '--exec', action='store_true',
               help='Shoot amoeba afterwards')
p.add_argument('in', help='Input file', metavar='INFILE')
p.add_argument('outs', nargs='*', help='Output file(s)',
               metavar='OUTFILE')

print("=== Usage message:")
p.print_usage()

print("\n=== Help message:")
p.print_help()

test(p, ['ingoat'])
test(p, ['-x', 'Brian'])
test(p, ['--exec', 'Brian', 'Reg', 'Dirk'])
test(p, ['-n', 'Brian', 'Reg', 'Dirk'])
test(p, ['--name=Pinnet', 'notlob', 'bolton'])
test(p, ['--nosuch', 'Centurion'])

Output of this script:

=== Usage message:
usage: larch [-h] [-n NAME] [-x] INFILE [OUTFILE [OUTFILE ...]]

=== Help message:
usage: larch [-h] [-n NAME] [-x] INFILE [OUTFILE [OUTFILE ...]]

Number 1: The Larch

positional arguments:
  INFILE                Input file
  OUTFILE               Output file(s)

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name your amoeba
  -x, --exec            Shoot amoeba afterwards

=== Test with ['ingoat']
{'in': 'ingoat', 'name': 'Dinsdale', 'outs': [], 'exec': False}

=== Test with ['-x', 'Brian']
{'in': 'Brian', 'name': 'Dinsdale', 'outs': [], 'exec': True}

=== Test with ['--exec', 'Brian', 'Reg', 'Dirk']
{'in': 'Brian', 'name': 'Dinsdale', 'outs': ['Reg', 'Dirk'], 'exec': True}

=== Test with ['-n', 'Brian', 'Reg', 'Dirk']
{'in': 'Reg', 'name': 'Brian', 'outs': ['Dirk'], 'exec': False}

=== Test with ['--name=Pinnet', 'notlob', 'bolton']
{'in': 'notlob', 'name': 'Pinnet', 'outs': ['bolton'], 'exec': False}

=== Test with ['--nosuch', 'Centurion']
usage: larch [-h] [-n NAME] [-x] INFILE [OUTFILE [OUTFILE ...]]
larch: error: unrecognized arguments: --nosuch

Notes on this example:

  • The print_function import uses the Python 3.x print() function; see Section 22.9, “The print() function”.

  • The vars() function is used to convert the argparse.Namespace instance returned by the .parse_args() method to a dictionary for display; see Section 21.22, “vars(): Local variables”.

  • The last time the test() function is called, the function does not return, because the specified set of options is not valid. The last two lines shown in the output below were sent to sys.stderr, not to sys.stdout like all the preceding lines.

28.10.6. Other useful ArgumentParser methods

These methods are available on your ArgumentParser instance:

.print_usage(file=None)

Prints the short summary of argument usage. The default file is sys.stdout.

.print_help(file=None)

Prints the full summary of argument usage, including the help text for each argument. The default file is sys.stdout.

.format_usage()

Formats the short summary of argument usage and returns it as a string.

.format_help()

Formats the full help text and returns it as a string.

.exit(status=0, message=None)

Terminates execution with status 0 (or the status value you provide). If you provide a message string, that message will be printed before termination.

.error(message)

Prints the usage message, plus the message string you provide, then terminates execution with status 2.

.add_mutually_exclusive_group(required=False)

If you have two or more options that cannot be specified on the same command line, use this method to create an option group. Then call the .add_argument() on the group instance to add these options. If you specify required=True, the user is required supply one of the options in the group.

Suppose for example that you have two mutually exclusive options --english and --metric. This code would prohibit the user from specifying both at once:

p = argparse.ArgumentParser()
g = p.add_mutually_exclusive_group()
g.add_argument("-e", "--english", dest="isMetric", action="store_false")
g.add_argument("-m", "--metric", dest="isMetric", action="store_true")
.set_defaults(**kw)

Use this method to specify the default values of any variable. For each keyword argument n=v, the value of n in the result returned by .parse_args() will have value v in case the user does not specify a value explicitly.

For example, if you have two mutually exclusive options, but you don't require one or the other, the .set_defaults() method is a good way to specify the value of the option when neither is given. Here is an interactive example showing this technique.

>>> parser = argparse.ArgumentParser()
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument("-y", "--yes", dest="which", action="store_true")
>>> group.add_argument("-n", "--no", dest="which", action="store_false")
>>> parser.set_defaults(which=True)
>>> print parser.parse_args(["--no"])
Namespace(which=False)
>>> print parser.parse_args(["-y"])
Namespace(which=True)
>>> print parser.parse_args([])
Namespace(which=True)