Package schrodinger :: Package utils :: Module cmdline

Module cmdline

Functions and classes to assist in standard processing of command line arguments.

The preferred way to use this module is by the SingleDashOptionParser class, which subclasses the standard library's optparse.OptionParser. The SingleDashOptionParser class provides the standard -h and -v options and finds the script by parsing the 'version_source' argument provided to the constructor. Example usage:

   parser = SingleDashOptionParser(usage="%prog [<options>] <mae file>"
           version_source=__doc__)
   parser.add_option("-d", "-debug", action="store_true", 
           default=False,
           dest="debug", 
           help="print extra debugging output")
   options, args = parser.parse_args()

Command Line Guidelines

Form of Options

Long Options

Long options should use single-dash, not double dash. That is, use -verbose, not --verbose. (Note that this means that clustering of short options is not available. It also means that spaces are required between short options and values - i.e. -lquiet is not equivalent to -l quiet as it is in the default OptionParser.) Long options should not be all upper case, as that is reserved for job control options.

Boolean Options

For boolean options, prefer either -log vs <nothing> or -log vs. -nolog to anything that requires the specification of some true/false value to the option.

Usage messages

Usage messages should be explicitly defined when using the SingleDashOptionParser.

Form

Script usage statements should follow the style outlined in our printed documentation. Arguments are typically listed after options in the usage message. Whenever possible, the message should list all script options. Below is a glossary of markup symbols and examples:

<> Angle brackets denote a place where the user should provide a value, as opposed to typing the literal string in the usage statement. The contents of the <> braces appear as italic text in the printed documentation.
[] Square braces denote optional user input.
| A vertical bar separates mutually exclusive options in either square or curly brackets.
... Ellipsis denote optional, repeated arguments of the same type.
{} Curly braces denote 'required options'. Required options should be avoided. When a script can operate in multiple modes, please choose one as the default rather than requiring an option to be specified by the user with every invocation.

Examples

Usage: $SCHRODINGER/run cmdline_ex.py <file> ...
<file> represents a variable file name provided the user, ... means that the script allows, but does not require, subsequent file name arguments.
Usage: $SCHRODINGER/run cmdline_ex.py [-color blue|red] <file>
[-color blue|red] means that the -color flag is optional, and when present it needs one of two string literals, either blue or red. Note: the -color flag is not required and is truly "optional", the script does something useful without the -color switch modifier.
Usage: $SCHRODINGER/run cmdline_ex.py [-host localhost|<ip_address>] <file>
-host is an option that modifies the default behavior. -host consumes either the string literal localhost or a user-supplied IP address.

Classes

[hide private]

SingleDashOption
A class to automatically translate long options with single dashes into double dash long options, but still print out help with the single dash.

DelegatingIndentedHelpFormatter
An IndentedHelpFormatter class that allows an Option class to alter its own option string if it has a process_option_strings method.

SingleDashOptionParser
An OptionParser subclass that allows long options with a single dash.

Functions

[hide private]

main_wrapper(main, *args)
Wrap 'main' functions for improved user interaction.

print_version(version_source='')
Print the script version and exit.

version_string(version_source='')
Form a standard version string from a source string.

add_jobcontrol_options(parser, options=[1, 0, 3, 4, 6], group_options=True)
Adds common Job Control options to a SingleDashOptionParser instance.

add_standard_options(parser, options=[0, 1, 4, 5, 6, 7], group_options=True)
Adds standard options to a SingleDashOptionParser instance.

add_jobcontrol_diagnostic_options(parser, options=[11, 12, 13, 14, 15, 16], group_options=True)
Appends Job Control diagnostic options to SingleDashOptionParser instance.

_is_single_dash_long_opt(option)
Identify a single dash long option.

_bad_option_str(self)

Variables

[hide private]

version_re = re.compile(r'\$Revision: *(\S+) *\$')

ALL = 11

DEBUG = 6

DEBUGGER = 7

DRIVERHOST = 3

ENTRY = 12

HOST = 1

HOSTLIST = 2

HOSTS = 13

LIST = 14

LOCAL = 4

NICE = 9

NJOBS = 0

NOJOBID = 0

NOLAUNCH = 6

NOLOCAL = 5

NSTRUCTS = 1

RESTART = 7

RETRIES = 5

SAVE = 10

STRICT = 4

SUBHOST = 2

TMPDIR = 8

WAIT = 3

WHICH = 15

WHY = 16

__package__ = 'schrodinger.utils'

Function Details

[hide private]

main_wrapper(main, *args)

Wrap 'main' functions for improved user interaction.

This function will call the provided 'main' function while providing standard handling of SIGPIPE and SIGINT signals and KeyboardInterrupt exceptions so that a full stack trace is not printed when they are received.

Parameters:

main (callable) - The function that should be called.
args - Additional positional arguments will be passed to the provided main function when it is called.

print_version(version_source=`''`)

Print the script version and exit.

Parameters:

version_source (str) - The string to search for a Revision tag.

version_string(version_source=`''`)

Form a standard version string from a source string. The source string is searched for an embedded CVS Revision tag. If one is found, that is used as the script version. If no Revision tag is found, only Schrodinger python version information is included.

add_jobcontrol_options(parser, options=`[`1`,` 0`,` 3`,` 4`,` 6`]`, group_options=True)

Adds common Job Control options to a SingleDashOptionParser instance.

The options are specified as a list of module enums. Accepted values are WAIT, LOCAL, DEBUG, DEBUGGER, TMPDIR, NICE, SAVE, NOJOBID, and HOST or HOSTLIST (with HOSTLIST taking precedence if both are specified). HOSTLIST adds the -HOST option, but with a default value of "localhost:1" instead of the HOST default of "localhost". The default list is [HOST, NOJOBID, WAIT, LOCAL, DEBUG].

Note that HOST, TMPDIR and SAVE are 'top-level' options and are not passed down from the top-level script (i.e. $SCHRODINGER/run). These are available so the options appear in the command line help. There are functions in schrodinger.job.jobcontrol that get HOST information, and environment variables can be queried for TMPDIR and SAVE if needed.

Example usage:

   parser = cmdline.SingleDashOptionParser()     
   cmdline.add_jobcontrol_options(parser)
   (opts, args) = parser.parse_args() 
   if opts.wait:
      # Provide wait argument to launch invocation.
   if opts.local:
      # Use the cwd as the jobdir.

Parameters:

parser (SingleDashOptionParser) - Instance of this module's SingleDashOptionParser.
options (List) - List of module enums that indicate what options to add to the parser.
group_options - If True then group the added options (via an optparse.OptionGroup) in the help message under the header 'Job Control Options'.
group_options - Boolean

add_standard_options(parser, options=`[`0`,` 1`,` 4`,` 5`,` 6`,` 7`]`, group_options=True)


Adds standard options to a SingleDashOptionParser instance.

The options are specified as a list of module enums. Accepted values are
NJOBS, NSTRUCTS, STRICT, RETRIES, NOLAUNCH, and RESTART.

Please note that NJOBS and NSTRUCTS options are mutual exclusive.
    i. e. njobs = total_structures / structures_per_job
User can either provide njobs or structures_per_job; so one option is
affecting the other option (in short, in specifying one option it can set
the proper value for the other option), hence NJOBS and NSTRUCTS options
are mutual exclusive.

Example usage::
    parser = cmdline.SingleDashOptionParser()
    cmdline.add_standard_options(parser)
    (opts, args) = cmdline.parse_standard_options(parser, args)
    if opts.njobs:
       # Provide njob argument to launch invocation.

@param parser: Instance of this module's SingleDashOptionParser.
@type parser : SingleDashOptionParser

@param options: List of module enums that indicate what options to
                add to the parser.
@type options : List

@param group_options: If True then group the added options (via an
                      optparse.OptionGroup) in the help message under
                      the header 'Standard Options'.
@param group_options: Boolean

add_jobcontrol_diagnostic_options(parser, options=`[`11`,` 12`,` 13`,` 14`,` 15`,` 16`]`, group_options=True)

Appends Job Control diagnostic options to SingleDashOptionParser instance.

These options are added simply to improve documentation uniformity to python script command line interfaces. The top-level layer should report then exit without running the script. Thus, the application script can't act upon any of these flags.

Parameters:

parser (SingleDashOptionParser) - Instance of this module's SingleDashOptionParser.
options (list) - List of module enums that indicate what options to add to the parser.
group_options - If True then group the added options (via an optparse.OptionGroup) in the help message under the header 'Diagnostic Options (Provide information but the program will not run)'.
group_options - Boolean

Module cmdline

Command Line Guidelines

Form of Options

Long Options

Boolean Options

Usage messages

Form

Examples

main_wrapper(main, *args)

print_version(version_source='')

version_string(version_source='')

add_jobcontrol_options(parser, options=[1, 0, 3, 4, 6], group_options=True)

add_standard_options(parser, options=[0, 1, 4, 5, 6, 7], group_options=True)

add_jobcontrol_diagnostic_options(parser, options=[11, 12, 13, 14, 15, 16], group_options=True)

print_version(version_source=`''`)

version_string(version_source=`''`)

add_jobcontrol_options(parser, options=`[`1`,` 0`,` 3`,` 4`,` 6`]`, group_options=True)

add_standard_options(parser, options=`[`0`,` 1`,` 4`,` 5`,` 6`,` 7`]`, group_options=True)

add_jobcontrol_diagnostic_options(parser, options=`[`11`,` 12`,` 13`,` 14`,` 15`,` 16`]`, group_options=True)