HowTo: Parse Command Line Arguments

Version: 16.2

Table of Contents

Preface

Scripts can be written to access MineSight® data that do not necessarily run within a MineSight® product.

For example, you may want to run a nightly script that reads a database and updates a model file. This nightly script does not need to be executed within MineSight®-Compass, MineSight®-Interactive Planner or MineSight®-3D. It can simply run from the command line.

Taking the above example further, consider that you want to run the same nightly job, but update different model files. The name of the model file that you wish to update can become a parameter for the your script.

Assumptions

You have a working familiarity with Python, MineSight® Grail library, and writing scripts in general. In addition, you should be familiar with working with the command prompt.

Python Command Line Parsing

Command line parsing is a useful technique for getting input into your script via the command line. It is generally used when the number of options and parameters are small.

Reading the System Command Line Argument List

If you do not wish to implement a full blown command line parser, you can simply read the arguments directly from the sys.argv [1] parameter. For example, consider that your script only requires a input path to process, then you could simple attempt to get the argument, and if you fail, output an useful error. Something like this,

import sys

try:
  path = sys.argv[1] # 0 is the the program name
except IndexError, e:
  # Argument list is not long enough.
  print "error: require input path as argument"
  sys.exit(-1)

The above example is really only useful in this very simple case. Adding other options becomes tedious to parse effectively. With more complex requirements, one should consider Python's getopt [4] module--the subject of the next section.

Python's getopt module

The Python standard library is a rich library full of modules that are very useful to for routine tasks [2]. This general inclusion of useful modules falls under Python's "Batteries Included Philosophy" [3].

The getopt module is an example of a useful module [4] that performs command line parsing.

This module will allow you to define standard options and then proceed to parse the command line into options, which contain arguments, and parameters. You can then read these options and parameters and use them to run your script.

The command line is defined by all those arguments stored within the sys.argv list.

Command Line Definitions

Most command line parsing involves two types of data: options and parameters.

Parameter

A parameter is anything that is required to run a script. For example, the standard copy.exe requires a source and destination file as parameters,

copy source destination

you can not execute copy without providing these parameters.

Option

An option is an argument that will cause your script to behave differently. Continuing with the copy.exe as our example, consider that you can supply that script with /Y option, which cause copy not to prompt the user for an overwrite,

copy /Y source destination

The copy executable can run with or without /Y option, but it can not run without the source and destination parameters.

Part of the parsing of designing your script should be to consider what command line arguments are parameters and what command line arguments are options.

A Framework for Command Line Parsing

This section will discuss creating a useful framework for command line parsing.

We will go over the framework for command line parsing by creating a useful script that will query Python's on-line help, and spawn the web browser with the appropriate results.

The completed script is available for download.

Before we start, let use review the options and parameters we will need,

Parameter
query string
Options:
library version (--version) help (--help)

Now lets start to write our script. We will start with importing our standard imports, and define our options,

import sys
import webbrowser
import getopt

SHORT_OPTIONS = "hv:" # v takes an argument, hence ":"
LONG_OPTIONS = ["help", "version="]
HELP_OPTIONS = ["-h", "--help"]
VERSION_OPTIONS = ["-v", "--version"]
USAGE = """
Usage: pyhelp.py [--version version] [--help] search-string"

Parameter:
  search-string   List of search terms that you wish to search.

Options:
  --version (-v)  Indicates what library you want to search in,
                  values are 2.1, 2.2, 2.3 or current.
  --help (-h)     Displays this message.

Examples:

  pyhelp.py re
  pyhelp.py getopt
  pyhelp.py -v 2.2 getopt
""

The next step is to define our default options. To keep the options well organized, we will store them within a dictionary, using the appropriate key. Later, when we are parsing the command line options, we can store the user's requests in the same dictionary.

# This dictionary will hold our user options. Start by defining the
# defaults, if the user defines something else, we will override the
# default.
OPTIONS = {"--version":"2.2",  # default to 2.2 library
           "--help":0}         # 0 no help; 1 show help

Now we will write a function that will parse the command line and return both the user parameters and user options.

def parse_command_line():
   """Returns the options dictionary and parameters. Generates
   getopt.GetoptError if it can not process the command line.
   """
   opts, params = getopt.getopt(sys.argv[1:], SHORT_OPTIONS,
                    LONG_OPTIONS)
   # get the defaults
   options = OPTIONS.copy()
   for option, argument in opts:
       if option in HELP_OPTIONS:
           options["--help"] = 1
       if option in VERSION_OPTIONS:
           options["--version"] = argument
   return options, params

I will skip the actual construction of the URL for clarity, and go onto using the parse_command_line function.

if __name__=="__main__":
   try:
       options, params = parse_command_line()
   except getopt.GetoptError, e:
       print "error: " + str(e)
       print USAGE
       sys.exit(-1)

   if options["--help"]==1:
       print USAGE
       sys.exit()

   if not params:
       print "error: search parameters required."
       sys.exit(-2)

   url = make_url(options["--version"], params)
   webbrowser.open_new(url)

The script will read the command line arguments and proceed to compose a URL that will be opened in a web browser. For complete details (like how make_url works), consult the pyhelp.py script.

References

[1]"sys -- System-specific parameters and functions" Python Library Reference. 30 May 2003. 3 August 2004. <http://www.python.org/doc/2.2.3/lib/module-sys.html>
[2]Python Library Reference. 30 May 2003. 19 July 2004. <http://www.python.org/doc/2.2.3/lib/lib.html>
[3]PEP 208: 2.0 Batteries Included. 19 July 2004. <http://www.python.org/peps/pep-0206.html>
[4](1, 2) "getopt -- Parser for command line options" Python Library Reference. 30 May 2003. 19 July 2004. <http://www.python.org/doc/2.2.3/lib/module-getopt.html>
View document source. Generated on: 2024-04-16 17:27 UTC.