Python makes it very convenient to configure your script to take in certain command line inputs.
It’s important that you, as a writer of Python code, configure your scripts to take advantage of this, since it makes your scripts more modular. And modularity is the key to successful development, since it allows you to develop more quickly by building on a foundation that you’ve already put in place.
Plus, you can feel like a true champ when a colleague asks you for help and in no time you are able to provide them with a script you’ve already developed and which solves their exact conundrum.
The module I use in my Python scripts to allow for the passing of command line inputs is called argparse. It is not native to Python 2.7, so you will need to run the following command to install it in your virtual environment:
pip install argparse
I will be referencing this Python script throughout this example, so feel free to download and reference.
Once you have argparse installed, import it into your script and create a function to collect command line inputs. This is the format I use for that function:
def commandLineSetup(): commandParser = argparse.ArgumentParser(description="Pings an API link for data " "and outputs data to JSON file") commandParser.add_argument("-l", "--link", help="API link to ping for information") commandParser.add_argument("-o", "--outputfile", help="Name/Path of the JSON output file") args = commandParser.parse_args() return args.link, args.outputfile
Let’s break down what each of these elements means:
- commandLineSteup(): This is the name of our command line parsing function. You can name it whatever you want. commandLineSetup works for me!
- argparse.ArgumentParser: Here we are configuring the argument parser, which is the main object type of the argparse module. There are multiple variables you can configure when setting up this object. The main one I like to configure is the “description” variable. This provides users with some information about what your script does and what they should expect.
- add_argument: Here we are providing the ArgumentParser with information about what arguments to expect via the command line and how to differentiate one argument from another. For example, to run our script, we need two variables: a URL and an output file. Information about our URL will come after the string “-l” in the command line and information about our output file will come after the string “-o”. Additionally, we provide some help text to the user to clarify what these variables mean and what our scripts needs to run successfully.
- parse_args: This is a function of the ArgumentParser object class that we can use to parse the passed in arguments using our defined criteria.
- return: We return the parsed arguments from our function, commandLineSetup().
To utilize this function, we need to call it when our script begins to run.
This is my reference:
LINK, OUTPUT = commandLineSetup()
Notice that the order of the variable assignment in my call to the function mirrors the order of the variables in the return clause of the function. (Note: You do not need to capitalize your variables; for me, it’s a personal preference, since it allows me to clearly note which variables are passed in and which are not.)
Lastly, I include a conditional statement in my script to verify that I have indeed received all the variables necessary to run my operations successfully:
if not LINK or not OUTPUT: print str(datetime.datetime.now()) + " - Insufficient inputs provided" exit()
The conditional statement stops the script from running if I am missing both input variables and returns an error message in Terminal to notify the user of what has happened. As the developer, you can write as many conditionals as you want in your script. For example, I could have added a regex clause to verify that the passed in OUTPUT string contains a “.json” file extension:
if re.match(r'(\.json)$', OUTPUT) == None: print str(datetime.datetime.now()) + " - Incorrect format for JSON file detected" exit()
Similarly, I could have set up a different conditional statement to verify that the passed in link is a valid URL.
Once you’ve set up your argument parsing function, you can do all kinds of nifty things in Terminal. For example, by using the command “–h”, you can return information about what your script does and what variables it anticipates:
If we pass in information for our variables, we can see that the script is able to run to completion:
We can also test that the opposite is true: that if we don’t pass certain variables to our script, that it will fail with an error message:
Isn’t this nice?
I encourage you to know how to parse command line arguments in your Python scripts and to try to do this for all your scripts so that you can add modularity to them and impress your friends.
My complete Python example (used in this post) is available here.
You can learn more about the argparse module here.