Package wsatools :: Module CLI
[hide private]

Module CLI

source code

Command-line interface tool. All scripts that require a command-line interface should use this tool, replacing the Python getopt module.

The purpose of the command-line interface (CLI) tool is to make the command-line interface both consistent and powerful for every VDFS script, enabling the operator a lot of control without having to hack the script. Furthermore, it automatically provides a lot of error checking to make the script as robust as possible, as well as a --help/-h option documenting the complete command-line interface for the script.

Usage

Import as:

   from wsatools.CLI import CLI

Define your list of program arguments and program options in a global part of your module that is processed on import - this makes the options globally accessible, and any module that imports this module will then automatically inherit these command line options. For command-line options associated with a class it may be clearer to define them within the class definition following the declaration of class member variables (see e.g. invocations.cu19.cu19.Cu19 class definition). To define the list program arguments append CLI.Argument objects to the CLI.progArgs list, and to define the list of program options append CLI.Option to the CLI.progOpts list:

   CLI.progArgs.append(CLI.Argument('surveyID', example='1',
                                    isValOK=lambda x: x.isdigit()))
   CLI.progOpts += [
       # Example of a boolean option flag - default value is always false
       CLI.Option('a', 'append',
                  'append tables to any pre-existing release database '
                  'of the same name'),
       # Example of an option with an argument that has a default value
       CLI.Option('b', 'begin',
                  'first observation date to release e.g. 2004-04-01',
                  argument='DATE',
                  default=str(ObsCal.earlyDefaultDateTime.date),
                  isValOK=CLI.isDateOK),
       # Example of an option with an argument with no default value
       CLI.Option('r', 'rerun',
                  'just apply to re-transfered files in this log',
                  argument='FILE', isValOK=CLI.assertFileExists)]

For full details on command-line argument and option definitions please to the CLI.Argument and CLI.Option class documentation respectively.

To change the default value of an inherited command-line argument:

   CLI.progArgs['comment'] = "Updating catalogue data"

To delete an inherited command-line argument/option:

   CLI.progArgs.remove('programmeID')

Then to process the command-line arguments/options, start your script with this as the first line:

   cli = CLI("Script's name", '$Revision: 9505 $',
             "This script does stuff to the given survey.")

This line will cause the script to exit straight away if the user has requested help, and the help screen will start with this information. It is important to use this script documentation to document the script's mandatory arguments, as shown in this example. The documentation can be taken from the first sentence of a docstring by referencing the docstring with the built-in Python __doc__ variable, or the docstring of a class e.g. Cu19.__doc__. This line also performs value tests on command-line options so that errors are caught early.

To then access the command-line options/arguments use CLI.getArg(), CLI.getOpt(), remembering that these functions will always return strings (unless it is a boolean option, in which case it will be True/False) - this is because the command-line can only pass strings as it has no knowledge of Python types (and this module does no automatic conversion):

   # Example of a mandatory program argument
   surveyID = int(cli.getArg('surveyID'))

   # Example of a boolean flag option
   appendDb = cli.getOpt('append')

   # Example of an option with an argument
   beginDate = utils.makeDateTime(cli.getOpt('begin'))

   # Example of an option with an argument without default value
   if cli.getOpt('rerun'):
       filePathName = cli.getOpt('rerun')
       contents = file(filePathName).readlines()

Note:


To Do:

Author: R.S. Collins

Organization: WFAU, IfA, University of Edinburgh

Classes [hide private]
  ArgGroup
Container to store the specified set of arguments required by the program.
  OptGroup
Container to store the specified set of command-line options specified by the program.
  CLI
Command-line interface tool - manages command line arguments.
    Errors & Exceptions
  MalformedValueError
An exception due to an incorrectly typed argument value.
  MissingArgumentError
An exception due to an incorrect number of supplied arguments.
Variables [hide private]
  __package__ = 'wsatools'