Home | Trees | Indices | Help |
|
---|
|
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.
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:
None
, which can be easily tested against.
Author: R.S. Collins
Organization: WFAU, IfA, University of Edinburgh
|
|||
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. |
|
|||
__package__ =
|
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0.1 on Mon Sep 8 15:46:42 2014 | http://epydoc.sourceforge.net |