10 tips for passing arguments to Python script
When writing some Python utility scripts, you may wish to make your script as flexible as possible so that people can use it in different ways. One approach is to parameterize some of the variables originally hard coded in the script, and pass them as arguments to your script. If you have only 1 or 2 arguments, you may find sys.argv is good enough since you can easily access the arguments by the index from argv list. The limitation is also obvious, as you will find it’s difficult to manage when there are more arguments, and some are mandatory and some are optional, also you cannot specify the acceptable data type and add proper description for each argument etc.
In this article, we will be discussing some tips for the argparse package, which provides easier way to manage your input arguments.
To get started, you shall import this package into your script, and try to run with some sample code like below:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
print(args)
Customize your prefix_chars
Most of time you would see people use “-” before the argument name, you can change this default behavior to support more prefix characters, such as + or \ etc. To do that, you can specify them in prefix_chars when initializing the argument parser, for instance:
parser = argparse.ArgumentParser(prefix_chars='-+/', description="This is to demonstrate multiple prefix characters")
parser.add_argument("+a", "++add")
parser.add_argument("-s", "--sub")
parser.add_argument("/d", "//dir")
args = parser.parse_args()
print(args)
When you save above as argumentparser.py file and call it with below input arguments, you shall see all the arguments are parsed correctly as per expected:
>>python argumentparser.py +a 1 -s 2 /d python Namespace(add='1', dir='python', sub='2')
Do take note that, if your argument name contains the prefix character “-“, you may see “-” character being replaced to “_”. For example, your argument name read-only would be replaced to read_only, and you shall use args.read_only to reference the value.
Argument data type
When you are adding new arguments, the default data type is always string, so whatever values followed behind the argument name will be converted into a string. Argument parser supports all immutable data types, so you can specify a data type and let argument parser to validate if correct data type has been passed in. E.g.:
parser.add_argument("-c", "--count", type=int)
You shall see the below validation error if incorrect data type has been passed in:
>>python argumentparser.py -c 1.5 usage: argumentparser.py [-h] [-c COUNT] argumentparser.py: error: argument -c/--count: invalid int value: '1.5'
Various argument actions
The action keyword in add_argument allows you to specify how you want to handle the arguments when they are passed into the script. Some of the commonly used actions are:
- store – default behavior
- store_const – work together with const keyword to store it’s value
- store_true or store_false – set the argument value to True or False
- append – allows the same argument to appear multiple times and store the argument values into a list
- append_const – same as append, but it will store the value from const keyword
- count – count how many times the argument appears
Below are some examples:
parser.add_argument('-a', '--auto', action="store_true", help="to run automatically")
parser.add_argument("-k", "--kelvin",
action="store_const",
const=273.15,
help="The constant to convert Celsius to Kelvin temperature")
parser.add_argument("-t", "--temperature",
type=float,
action="append",
default=[],
help="Celsius temperature to be used in %(prog)s")
parser.add_argument('--age', dest='criteria', action='append_const', const=18)
parser.add_argument('--gender',dest='criteria', action='append_const', const="male")
parser.add_argument("-c", "--count", action="count")
When you run in the command line, you shall see all these arguments are parsed correctly and stored into the respective variables:
>>python argumentparser.py -k -t 35.1 -t 37.5 --age --gender -cc -a Namespace(auto=True, count=2, criteria=[18, 'male'], kelvin=273.15, temperature=[35.1, 37.5])
In Python version 3.8 and later, you can also extend your own class from argparse.Action and pass it to the action.
Use action=”append” or narg=”+” ?
If you want to collect a list of values from a particular input argument, you have two options:
- specify action = “append”
- specify the nargs=”+”
For the below code, both “amount” and “nums” will be able to store a list of values from the input:
parser.add_argument("-a", "--amount",
type=float,
action="append")
parser.add_argument("-n", "--nums", nargs="+")
The only difference is that, for “append” action, you will need to repeat the argument name whenever you need to add extra values. While for “nargs”, you just need to put all the space separated values after the argument name. E.g.:
>>python argumentparser.py -a 1 -a 2 -n 3 4 Namespace(amount=[1.0, 2.0], nums=['3', '4'])
You may notice that if have any argument with nargs=”+”, it’s better always put it after all the positional arguments, as the argument parser would take your positional argument as part of the previous argument. (see the example in the next tips)
Mixing of positional and optional arguments
When there is no prefix characters used in the argument name, the argument parser will treat it as a positional argument. For instance:
parser.add_argument("caller", help="The process that invoke this script")
parser.add_argument("-c", "--count")
When you check the help for this script, you shall see caller is taken as positional argument.
>>python argumentparser.py -h usage: argumentparser.py [-h] [-c COUNT] caller positional arguments: caller The process that invoke this script optional arguments: -h, --help show this help message and exit -c COUNT, --count COUNT
Positional arguments are considered as mandatory, so Python will throw error if they are not specified when calling the script. You can put positional argument at any place of your input argument stream. E.g.:
>>python argumentparser.py -c 2 "cmd.exe" >>python argumentparser.py "cmd.exe" -c 2 Namespace(caller='cmd.exe', count=2)
Python is smart enough to interpret and assign the values to the correct variables unless there is some confusion when trying to interpret your input arguments, e.g.: If you use nargs to indicate multiple argument values can be passed in:
parser.add_argument("-c", "--count", nargs='+')
And putting your positional argument behind this argument will cause error, because all the values behind “-c” will be taken as the values for “count”
>>python argumentparser.py -c 1 3 "cmd.exe" usage: argumentparser.py [-h] [-c COUNT [COUNT ...]] caller argumentparser.py: error: the following arguments are required: caller
Difference between const vs default
const keyword usually works together with action option – store_const or append_const to store the value from the const keyword when the argument appears. If the argument is not supplied, the argument variable will be set as None. Consider the below two arguments:
parser.add_argument("-k", "--kelvin",
action="store_const",
const=273.15,
help="The constant to convert celsius to Kelvin temperature")
parser.add_argument("-c", "--count", default=0)
If you run with below input arguments, you shall the similar result as below:
>>python argumentparser.py -k Namespace(count=0, kelvin=273.15) >>python argumentparser.py -c 1 Namespace(count='1', kelvin=None) >>python argumentparser.py -k 270 usage: argumentparser.py [-h] [-k] [-c COUNT] argumentparser.py: error: unrecognized arguments: 270
So with const keyword, you basically cannot specify any other values. but still you can add a default value, so that when the argument is supplied, the default value will be set as the default value rather than None.
Mandatory optional argument?
If you would like your optional argument to be mandatory (although it sounds a bit weird), you can specify the required option as True in the add_argument method, e.g.:
parser.add_argument("--data-type", required=True)
With required as True, even you have specified the default option, python will still prompt error saying the argument –data-type is required.
Ignore case in choice option
Image you are implementing some automation scripts to be triggered in various mode, and you would like to limit the options to be accepted for this mode argument, you can specify a list of values in the choices keyword when adding the argument:
parser.add_argument('-m','--mode', choices=['AUTO','SCHEDULER','SEMI-AUTO'])
But you may realize one problem as when you specify “auto” or “Auto”, you would see below error message:
>>python argumentparser.py -m "auto"
usage: argumentparser.py [-h] [-m {AUTO,SCHEDULER,SEMI-AUTO}]
argumentparser.py: error: argument -m/--mode: invalid choice: 'auto' (choose from 'AUTO', 'SCHEDULER', 'SEMI-AUTO')
By default, the argument parser will compare the values in case sensitive manner. To ignore the cases, you can specify a type keyword and transform the input values into upper or lower case:
parser.add_argument('-m','--mode', choices=['AUTO','SCHEDULER','SEMI-AUTO'], type=str.upper)
Conflicting options
Sometimes defining some mutually exclusive arguments can be very useful as you do not wish the two or multiple options to be used at the same time. argparse package also provides a easy way to group these options with necessary validations on the input arguments. For instance, you can group the “auto” and “on-demand” mode into the mutually exclusive group, so that only one mode can be activated at one time:
mode_group = parser.add_mutually_exclusive_group()
mode_group.add_argument('-a', '--auto', action="store_true", help="to run automatically")
mode_group.add_argument('-d', '--on-demand', action="store_true", help="to run on demand")
If both arguments are supplied, you would see the below error message:
>>python argumentparser.py -d -a usage: argumentparser.py [-h] [-a | -d] argumentparser.py: error: argument -a/--auto: not allowed with argument -d/--on-demand
Conclusion
argpase package is super useful when you need to write some script to be executed from the command line. In this article, we have reviewed through some tips that might help you to extend your understanding on the different use cases for each individual options argparse provided. If you have more complicated use case, you may want to read further on the official documentation such as the sub-commands and file type etc.
no thanks