Python ArgParse Module Notes
Page Contents
References
Todo
parser.add_subparsers()
parser = subparsers.add_parser()
- parser.set_defaults(func=...)
ArgParse Python Module
Really bloody useful for parsing command line options given to scripts with ease!
import argparse parser = argparse.ArgumentParser(description="Describe your program here") # Define arguments args = parser.parse_args()
You can add_argument()'s to the parser. Arguments can be positional or optional. Optional arguments are generally specified as a short command, e.g. -h, and/or as a long command, e.g. --help along with an action to perform if the command is received. Positional arguments are just defined as a name with no preceding hyphenated prefix.
Actions
For example, to add version information to the command line you could do:
parser.add_argument( "-v", "--version", action = 'version', version = '%(prog)s {version}'.format(version=__version__), help = ("print version information"), )
If you want to store the value of an argument in some way you will want to use one of the following actions (there are more possibilities - see the Python docs):
store
To store a conditional you would do something like this:
parser.add_argument("-j", "--jehtech", action="store") args = parser.parse_args() print args.jehtech
If you then ran your program with the command line argument python prog.py --jehtech "Hi JehTech" the variable args.jehtech would hold the string "Hi JehTech"
To store a positional you would do something like this:
parser.add_argument("jehtech_positional") args = parser.parse_args() print args.jehtech_positional
If you want your program as python prog.py "Hi positional" the variable args.jehtech_positional would hold the string "Hi positional".
store_const (and store_true/store_false)
Use these to store the presense of a flag that has no value associated with it. For example, a verbose flag, probably stands alone, i.e., the flag doesn't have a value associated with it. The const value is what is stored in the parser variable.
parser.add_argument( "-T", "--test_mode", const = "This the value to store", action = 'store_const', ) args = parser.parse_args()
If the option is specified on the command line the property args.test_mode will contain the string "This is the value to store". If it was not specified the property will be None.
You can specify a default value to be stored if the option is not specified on the command line using the default=... argument to add_argument().
parser.add_argument( "-T", "--test_mode", const = "This the value to store", default = "Default value if --test_mode not specified", action = "store_const", ) args = parser.parse_args()
The actions store_true and store_false are just shorthand actions for when you would normally set const to either True or False.
I.e.,
parser.add_argument( "-T", "--test_mode" const = True action = 'store_const' )
Is equivalent to...
parser.add_argument( "-T", "--test_mode", action="store_true")
append
This will append values to a list. See Python docs...
Argument Types
By default all arguments are parsed into strings. If you want to have argparse convert the arguments
into other types for you, use the type=...
parameter of add_argument()
.
The type=
argument takes any callable that accepts a string parameter and returns a type.
So, for example, the int
function can be passed to add_argument
.
parser.add_argument( "-i", "--an-int-param" action = 'store' type = int )
If you wanted a positive integer, for example, you could define your own callable...
positive_int(value): ivalue = int(value) if ivalue <= 0: raise argparse.ArgumentTypeError("Negative integers are not allowed") return ivalue parser = argparse.ArgumentParser(...) parser.add_argument( "-u", "--a-uint-param", action = "store", type = positive_int)
Choices
If you want to check the values of the parameter match a list of choices, after type conversion
you can use the choices=(generator|list)
argument.
To restrict a param to a range of integers use choices=range(min,max)
, or to restrict
a string to a list of values use choices=["some", "list", "of", "strings]
.
Optional Posisitional When Named Argument Provided
If you want to have command --some-arg xxx
work when otherwise a positional would be required,
e.g., command --any-other-arg xxx position-arg
.
Argprase can't do this out-of-the-box. The easiest way appears to be to use nargs="?"
for the positional argument and check manually once the arguments have been parsed:
parser.add_argument("positional1", nargs="?") parser.add_argument("positional-not-needed", required=False) args = parser.parse_args() if args.positional_not_needed is None and args.positional1 is None: parser.print_usage() parser.exit(1, "Positional argument required")
Help And Epilog
If you want a chunk of text at the bottom of the help message there are two options.
- Pass in the epilog as an argument to the
ArgumentParser()
constructor using theepilog
keyword. - Or, set the
epilog
property on theArgumentParser
instance.