Writing Command Line Utilities with Python and Optparse

by Ralph Heimburger

October 10, 2009

Introduction

Writing command line utilities with Python and optparse explores some of the more powerful aspects of Python development. From simple directory management to more complex searching utilities and APIs, Python offers the developer both ease and power. This article explores the capabilities of the optparse library which was introduced in Python 2.3. For those familiar with the getopt module, optparse is much more convenient, flexible and powerful.

First, let's take a quick look at optparse, the "more powerful command line option parser". This powerful library greatly simplifies option parsing and as you will see, offers greater flexibility than simply inspecting sys.argv. With optparse, you can control not only what options are validated, but how to handle defaults, etc.

Let's take a basic example. I want to write a command line utility to accept a number of parameters:

• -i: ignore case
• -l: List Files only
• -r: recursive
• -s: summary
• -v: version
• -h: help

I also want each parameter to become a boolean condition, for example options.ignorecase would be evaluated as True or False, although it is possible to have parameters as string, int, etc.

The following code sample is how I would use optparse to implement my parameters:

      import optparse
  
      parser=optparse.OptionParser()
      parser.add_option(
          '-i','--ignorecase',
          dest='ignorecase',
          default=False,
          action="store_true",
          help='''Ignore Case.'''
      )
      parser.add_option(
          '-l','--listonly',
          dest='list_only',
          default=False,
          action="store_true",
          help='''List Files only.'''
      )
      parser.add_option(
          '-s','--summary',
          dest='summary',
          default=False,
          action="store_true",
          help='''Show summary for each folder.'''
      )
      parser.add_option(
          '-r','--recursive',
          dest='recursive',
          default=False,
          action="store_true",
          help='''recursivly search rootpath.'''
      )
      parser.add_option(
          '-v','--version',
          dest='version',
          default=False,
          action="store_true",
          help='''Show xfind Version.'''
      )
  
      options,args=parser.parse_args() 

parser.add_option is the method I call to add my command line parameters to my utility. I can reference my options by both '-' and '- -' option strings, also help seems to come for free which saves me a lot of extra coding. By passing the type attribute, validation is also included.

The basic syntax of add_option is:

  parser.add_option("-i", "--ignorecase"
                     ,action="store_true"
                    , dest="ignorecase"
                     , default=False
                     , help="Ignore case (case insensitive search)")

Notice the action attribute. This is how I instruct optparse to store the value returned when I receive this command line option which gives greater flexibility and validation. The six built-in option types: "string", "int", "long", "choice", "float" and "complex". It is possible to add additional or new options types by extending optparse (see the official optparse documentation for more information).

Putting it together

Let's create a basic Python command line utility called c.py which will eventually become a standalone executable and placed into my utilities folder.

  #!/usr/local/bin/python
  VERSION='0.20'
  if __name__== '__main__':
      import os, sys
      import re
      import optparse
  
      parser=optparse.OptionParser()
      parser.add_option(
          '-i','--ignorecase',
          dest='ignore_case',
          default=False,
          action="store_true",
          help='''Ignore Case.'''
      )
      parser.add_option(
          '-l','--listonly',
          dest='list_only',
          default=False,
          action="store_true",
          help='''List Files only.'''
      )
      parser.add_option(
          '-s','--summary',
          dest='summary',
          default=False,
          action="store_true",
          help='''Show summary for each folder.'''
      )
      parser.add_option(
          '-r','--recursive',
          dest='recursive',
          default=False,
          action="store_true",
          help='''recursivly search rootpath.'''
      )
      parser.add_option(
          '-v','--version',
          dest='version',
          default=False,
          action="store_true",
          help='''Show xfind Version.'''
      )
      options,args=parser.parse_args()    
      scriptname=os.path.basename(__file__)
      if options.version:
         print '%s: Version %s' %(scriptname,VERSION)
         raise SystemExit

Testing c.py from the command line:

  $ c.py --help
  Usage: c.py [options]

Options:
  -h, --help        show this help message and exit
  -i, --ignorecase  Ignore Case.
  -l, --listonly    List Files only.
  -s, --summary     Show summary for each folder.
  -r, --recursive   recursivly search rootpath.
  -v, --version     Show xfind Version.

$ c.py -v
c.py: Version 0.20

Notice in the above code sample I did not have to specifically code for the '-h'/'--help' and when I wanted to test if I received the version option, I simply referenced it as options.version (true/false). I can use options. <OPTIONNAME> throughout my code as these are the returned argument values that optparse parsed and per my instructions stored.

Summary

If you are considering using Python for writing command line utilities, you really should consider optparse, as it greatly simplifies argument passing and handling. More information can be found on the official optparse documentation page, http://docs.python.org/library/optparse.html.