Overview
With Python being a highly regarded programming language, in addition to having help for many working techniques and plenty of libraries that make command-line argument processing straightforward – it is develop into extensively used to create command line instruments for a lot of functions. These instruments can vary from easy CLI apps to people who are extra advanced, like AWS’ awscli device.
Advanced instruments like this are usually managed by the person through command line arguments, which permits the person to make use of particular instructions, set choices, and extra. For instance, these choices might inform the device to output further info, learn information from a specified supply, or ship output to a sure location.
Normally, arguments are handed to CLI instruments in a different way, relying in your working system:
- Unix-like:
-adopted by a letter, like-h, or--adopted by a phrase, like--help - Home windows:
/adopted by both a letter, or phrase, like/assist
These completely different approaches exist on account of historic causes. Many packages on Unix-like techniques help each the only and double sprint notation. The one sprint notation is usually used with single letter choices, whereas double dashes current a extra readable choices checklist, which is especially helpful for advanced choices that must be extra specific.
Word: On this article we’ll solely be specializing in the Unix-like format of - and --.
Understand that each the title and the that means of an argument are particular to a program – there is no such thing as a normal definition, aside from a couple of frequent conventions like --help for additional info on the utilization of the device. Because the developer of a Python script, you’ll determine which arguments to supply to the caller and what they do. This requires correct analysis.
As your checklist of accessible arguments grows, your code will develop into extra advanced in attempting to precisely parse them. Fortunately, in Python there are a selection of libraries obtainable that will help you with this. We’ll cowl a couple of of the most typical options, which vary from “do-it-yourself” with sys.argv, to the “done-for-you” method with argparse.
Dealing with Command Line Arguments with Python
Python 3+ and the ecosystem round helps various alternative ways of dealing with command line arguments. There are many libraries that fascilitate parsing command-line arguments.
The built-in manner is to make use of the sys module. By way of names, and its utilization, it relates on to the C library (libc).
The second manner is the getopt module, which handles each brief and lengthy choices, together with the analysis of the parameter values.
The argparse module, which is derived from the optparse module (obtainable as much as Python 2.7).
The docopt module, which is obtainable on GitHub, additionally permits the identical performance.
Not too long ago, the absl library has additionally been gaining steam, as a method to exchange optparse and getopt().
Every of those methods has their execs and cons, so it is price evaluating every to see which fits your wants finest.
The sys Module
This can be a primary module that has been shipped with Python from the early days. It takes a really related method to the C library utilizing argc/argv to entry the arguments. The sys module implements the command line arguments in a easy checklist construction named sys.argv.
Every checklist component represents a single argument. The primary merchandise within the checklist,
sys.argv[0], is the title of the Python script. The remainder of the checklist parts,sys.argv[1]tosys.argv[n], are the command line arguments 2 by n.
As a delimiter between the arguments, an area is used. Argument values that comprise an area in it should be surrounded by quotes so as to be correctly parsed by sys.
The equal of argc is simply the variety of parts within the checklist. To acquire this worth, use the Python len() operator. We’ll present this in a code instance afterward.
Printing the First CLI Argument
On this first instance, our script will decide the way in which it was known as. This info is saved within the first command line argument, listed with 0. The code under exhibits the way you acquire the title of your Python script:
import sys
print("The script has the title %s" % (sys.argv[0])
Save this code in a file named arguments-program-name.py, after which name it as proven under. The output is as follows and incorporates the file title, together with its full path:
$ python arguments-program-name.py
The script has the title arguments-program-name.py
$ python /house/person/arguments-program-name.py
The script has the title /house/person/arguments-program-name.py
As you possibly can see from the second name above, we not solely get the title of the Python file, but in addition the complete path used to name it.
Counting the Variety of Arguments
On this second instance we merely depend the variety of command line arguments utilizing the built-in len() technique. sys.argv is the checklist that we’ve got to look at. Within the code under, we get the variety of arguments after which subtract 1 as a result of a type of arguments (i.e. the primary one) is all the time set because the title of the file, which is not all the time helpful to us. Thus, the precise variety of arguments handed by the person is len(sys.argv) - 1:
import sys
arguments = len(sys.argv) - 1
print ("The script known as with %i arguments" % (arguments))
Save and title this file arguments-count.py. Some examples of calling this script is proven under. This contains three completely different situations:
- A name with none additional command line arguments
- A name with two arguments
- A name with two arguments, the place the second is a quoted string containing an area
$ python arguments-count.py
The script known as with 0 arguments
$ python arguments-count.py --assist me
The script known as with 2 arguments
$ python arguments-count.py --option "lengthy string"
The script known as with 2 arguments
Iterating Via Arguments
Our third instance outputs each single argument despatched to the Python script, besides this system title itself. Subsequently, we loop by the command line arguments beginning with the second checklist component. Recall that that is index 1 since lists are 0-based in Python:
import sys
arguments = len(sys.argv) - 1
place = 1
whereas (arguments >= place):
print ("Parameter %i: %s" % (place, sys.argv[position]))
place = place + 1
Beneath we name our code, which was saved to the file arguments-output.py. As achieved with our earlier instance, the output illustrates three completely different calls:
- A name with none arguments
- A name with two arguments
- A name with two arguments, the place the second argument is a quoted string containing an area
$ python arguments-output.py
$ python arguments-output.py --assist me
Parameter 1: --help
Parameter 2: me
$ python arguments-output.py --option "lengthy string"
Parameter 1: --option
Parameter 2: lengthy string
Bear in mind, the purpose of displaying the quoted string instance is that parameters are normally delimited by an area, until they’re surrounded by quotes.
Abseil Flags (absl)
Abseil’s Flags library is supposed to deliver command line arguments to manufacturing, with distributed command line arguments. When a module makes use of command-line flags, and is imported into one other module – the opposite module imports the flags as effectively, and might course of them by forwarding them to the imported module.
This makes advanced command-line arguments shared between modules simpler and fewer verbose.
Moreover, the library helps you to outline the default values, descriptions of, and information kind of the arguments, so further checks and conversions aren’t obligatory.
from absl import flags
import sys
flags.DEFINE_string('title', 'Consumer', 'The title of the person.')
FLAGS = flags.FLAGS
FLAGS(sys.argv)
print(f"Hiya {FLAGS.title}!")
The supported information sorts are:
DEFINE_integer()DEFINE_string()DEFINE_bool()DEFINE_enum()DEFINE_list()DEFINE_float()
In addition to DEFINE_multi_integer(), DEFINE_multi_string() and DEFINE_multi_enum() for multi-argument enter. Moreover, working --help, --helpfull, and many others. print the present flags and their descriptions, in several codecs.
Take a look at our hands-on, sensible information to studying Git, with best-practices, industry-accepted requirements, and included cheat sheet. Cease Googling Git instructions and truly be taught it!
The library additionally lets you outline validations – each by way of vary, comparable to integer-based values having an upper_bound or lower_bound that is acceptable, and working arbitrary strategies to examine for values:
def validate_name(worth):
return len(worth) > 15
flags.register_validator('title',
validate_name,
message='Title is over 15 characters lengthy.',
flag_values=FLAGS)
Gathering these right into a concrete instance:
from absl import flags
import sys
flags.DEFINE_string('title', 'Consumer', 'The title of the person.')
flags.DEFINE_integer('duties', 0, 'The variety of duties a person has.', lower_bound=0)
FLAGS = flags.FLAGS
FLAGS(sys.argv)
print(f"{FLAGS.title} has {FLAGS.duties} duties to work on.")
$ python flags.py --name=John --tasks=5
John has 5 duties to work on.
$ python flags.py --name=John --tasks=-1
Traceback (most up-to-date name final):
File "/Library/Frameworks/Python.framework/Variations/3.9/lib/python3.9/site-packages/absl/flags/_flag.py", line 180, in _parse
return self.parser.parse(argument)
File "/Library/Frameworks/Python.framework/Variations/3.9/lib/python3.9/site-packages/absl/flags/_argument_parser.py", line 168, in parse
increase ValueError('%s isn't %s' % (val, self.syntactic_help))
ValueError: -1 isn't a non-negative integer
...
The argparse Module
The argparse module has been obtainable since Python 3.2, and an enhancement of the optparse module that exists as much as Python 2.7. The Python documentation incorporates an API description and a tutorial that covers all of the strategies intimately.
The module provides a command line interface with a standardized output, whereas the previous two options go away a lot of the work in your palms. argparse permits the verification of fastened and non-obligatory arguments, with title checking as both brief or lengthy model. As a default non-obligatory argument, it contains -h, together with its lengthy model --help. This argument is accompanied by a default assist message describing the accepted arguments.
The code under exhibits the parser initialization, and the output under that exhibits the essential name, adopted by the assistance message. In distinction to the Python calls we used within the earlier examples, remember to make use of Python 3 with these examples:
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
$ python3 arguments-argparse-basic.py
$ python3 arguments-argparse-basic.py -h
utilization: arguments-argparse-basic.py [-h]
non-obligatory arguments:
-h, --help present this assist message and exit
$ python3 arguments-argparse-basic.py --verbose
utilization: arguments-argparse-basic.py [-h]
arguments-argparse-basic.py: error: unrecognized arguments: --verbose
Within the subsequent step, we’ll add a customized description to the assistance message for our customers. Initializing the parser on this manner permits a further textual content. The code under shops the outline within the textual content variable, which is explicitly given to the argparse class because the description parameter. Calling this code under, you possibly can see what the output seems like:
import argparse
textual content = 'This can be a check program. It demonstrates the way to use the argparse module with a program description.'
parser = argparse.ArgumentParser(description=textual content)
parser.parse_args()
$ python3 arguments-argparse-description.py --assist
utilization: arguments-argparse-description.py [-h]
This can be a check program. It demonstrates the way to use the argparse module with a
program description.
non-obligatory arguments:
-h, --help present this assist message and exit
As the ultimate step we’ll add an non-obligatory argument named -V, which has a corresponding lengthy model argument named --version. To take action we use the strategy add_argument() that we name with three parameters (displayed for --version, solely):
- The title of the parameter:
--version - The assistance textual content for the parameter:
assist="present program model" - Motion (with out further worth):
motion="store_true"
The supply code for that’s displayed in under. Studying the arguments into the variable known as args is completed through the parse_args() technique from the parser object. Word that you simply submit each the brief and the lengthy model in a single name. Lastly, you examine if the attributes args.V or args.model are set and output the model message:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-V", "--version", assist="present program model", motion="store_true")
args = parser.parse_args()
if args.model:
print("That is myprogram model 0.1")
$ python3 arguments-argparse-optional.py -V
That is myprogram model 0.1
$ python3 arguments-argparse-optional.py --version
That is myprogram model 0.1
The --version argument doesn’t require a price to be given on the command line. That is why we set the motion argument to "store_true". In different instances you would possibly want a further assigned worth, for instance in case you specify a sure quantity, top, or width. That is proven within the subsequent instance. As a default case, please be aware that each one the arguments are interpreted as strings:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--width", "-w", assist="set output width")
args = parser.parse_args()
if args.width:
print("Set output width to %s" % args.width)
Right here we present what occurs when submitting completely different argument values. This contains each the brief and the lengthy model, in addition to the assistance message:
$ python3 arguments-argparse-optional2.py -w 10
Set output width to 10
$ python3 arguments-argparse-optional2.py --width 10
Set output width to 10
$ python3 arguments-argparse-optional2.py -h
utilization: arguments-argparse-optional2.py [-h] [--width WIDTH]
non-obligatory arguments:
-h, --help present this assist message and exit
--width WIDTH, -w WIDTH
set output width
The getopt Module
As you might have observed earlier than, the sys module splits the command line string into single sides solely. The Python getopt module goes a bit additional and extends the separation of the enter string by parameter validation. Primarily based on the getopt C perform, it permits each brief and lengthy choices, together with a price project.
In follow, it requires the sys module to course of enter information correctly. To take action, each the sys module and the getopt module should be loaded beforehand. Subsequent, from the checklist of enter parameters we take away the primary checklist component (see the code under), and retailer the remaining checklist of command line arguments within the variable known as argument_list:
import getopt, sys
full_cmd_arguments = sys.argv
argument_list = full_cmd_arguments[1:]
print argument_list
The arguments in argument_list can now be parsed utilizing the getopts() technique. However earlier than doing that, we have to inform getopts() about which parameters are legitimate. They’re outlined like this:
short_options = "ho:v"
long_options = ["help", "output=", "verbose"]
Which means that these arguments are ones we take into account to be legitimate, together with some additional information:
------------------------------------------
lengthy argument brief argument with worth
------------------------------------------
--help -h no
--output -o sure
--verbose -v no
------------------------------------------
You might need observed that the o brief choice was proceeded by a colon, :. This tells getopt that this selection needs to be assigned a price.
This now permits us to course of a listing of arguments. The getopt() technique requires three parameters to be configured – the checklist of precise arguments from argv, in addition to each the legitimate brief and lengthy choices (proven within the earlier code snippet).
The tactic name itself is saved in a try-catch-statement to cowl errors in the course of the analysis. An exception is raised if an argument is found that’s not a part of the checklist as outlined earlier than. The Python script will print the error message to the display, and exit with error code 2:
strive:
arguments, values = getopt.getopt(argument_list, short_options, long_options)
besides getopt.error as err:
print (str(err))
sys.exit(2)
Lastly, the arguments with the corresponding values are saved within the two variables named arguments and values. Now, you possibly can simply consider these variables in your code. We will use a for-loop to iterate by the checklist of acknowledged arguments, one entry after the following.
for current_argument, current_value in arguments:
if current_argument in ("-v", "--verbose"):
print ("Enabling verbose mode")
elif current_argument in ("-h", "--help"):
print ("Displaying assist")
elif current_argument in ("-o", "--output"):
print (("Enabling particular output mode (%s)") % (current_value))
Beneath you possibly can see the output from executing this code. We’ll present how this system reacts with each legitimate and invalid program arguments:
$ python arguments-getopt.py -h
Displaying assist
$ python arguments-getopt.py --assist
Displaying assist
$ python arguments-getopt.py --output=inexperienced --assist -v
Enabling particular output mode (inexperienced)
Displaying assist
Enabling verbose mode
$ python arguments-getopt.py -verbose
choice -e not acknowledged
The final name to our program could appear a bit complicated at first. To grasp it, you might want to know that the shorthand choices (typically additionally known as flags) can be utilized along with a single sprint. This enables your device to extra simply settle for many choices. For instance, calling python arguments-getopt.py -vh is similar as calling python arguments-getopt.py -v -h. So within the final name above, the getopt module thought the person was attempting to go -e as an choice, which is invalid.
Conclusion
On this article we confirmed many various strategies for retrieving command line arguments in Python, together with utilizing sys, getopt, and argparse. These modules differ in performance, some offering way more than others. sys is totally versatile, whereas each getoptand argparse require some construction. In distinction, they cowl many of the advanced work that sys leaves as much as you. After working by the examples offered, you need to be capable to decide which module fits your venture finest.
On this article we didn’t discuss different options just like the docopts module, we simply talked about it. This module follows a completely completely different method, and might be defined intimately in one of many subsequent articles.
References
