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=None, group_options=True)
Adds common Job Control options to a SingleDashOptionParser or argparse.ArgumentParser instance.

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

add_jobcontrol_diagnostic_options(parser, options=None, group_options=True)
Appends Job Control diagnostic options to SingleDashOptionParser or argparse.ArgumentParser instance.

_is_single_dash_long_opt(option)
Identify a single dash long option.

_bad_option_str(self)

create_argument_parser(*args, **kwargs)
Factory function to get an argparse.ArgumentParser with standard help and version added in a single dash fashion.

_get_option_container(parser, group_header=None)
Internal function to validate use of SingleDashOptionParser or argparse.ArgumentParser.

Variables

[hide private]

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

ALL = 11

DEBUG = 6

DEBUGGER = 7

DRIVERHOST = 3
hash(x)

ENTRY = 12

HOST = 1

HOSTLIST = 2

HOSTS = 13

JOBNAME = 19

LIST = 14

LOCAL = 4

NICE = 9

NJOBS = 0
hash(x)

NOJOBID = 0
hash(x)

NOLAUNCH = 6

NOLOCAL = 5

NSTRUCTS = 1

OPLSDIR = 18

RESTART = 7

RETRIES = 5

SAVE = 10

STRICT = 4

SUBHOST = 2

TMPDIR = 8

VIEWNAME = 17

WAIT = 3
hash(x)

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=None, group_options=True)

Adds common Job Control options to a SingleDashOptionParser or argparse.ArgumentParser instance.

The options are specified as a list of module enums. Note that HOSTLIST takes precedence if both HOST and HOSTLIST are specified. HOSTLIST adds the -HOST option, but with a default value of "localhost:1" instead of the HOST default of "localhost".

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 or ArgumentParser) - Instance of this module's SingleDashOptionParser or instance of argparse.ArgumentParser.
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, default_retries=None)


Adds standard options to a SingleDashOptionParser or
argparse.ArgumentParser 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 or
               insance of argparseArgumentParser.
@type parser : SingleDashOptionParser or ArgumentParser

@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

@param default_retries: The default number of retries to use (only 
                        applies is RETRIES is included in options)
@param default_retries: integer

add_jobcontrol_diagnostic_options(parser, options=None, group_options=True)

Appends Job Control diagnostic options to SingleDashOptionParser or argparse.ArgumentParser 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 or ArgumentParser) - Instance of this module's SingleDashOptionParser or instance of argparse.ArgumentParser.
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

create_argument_parser(*args, **kwargs)

Factory function to get an argparse.ArgumentParser with standard help and version added in a single dash fashion.

Takes the same arguments as argparse.ArgumentParser.

@type version_source unicode

Parameters:

version_source - A string containing a CVS Revision string like $Revision: 1.26 $. If not specified, it uses the Schrodinger python version number.

_get_option_container(parser, group_header=None)

Internal function to validate use of SingleDashOptionParser or argparse.ArgumentParser.

Parameters:

parser (SingleDashOptionParser or argparse.ArgumentParser) - parser object to be validated
group_options (Boolean) - If True, add group_options under the the opt_group_header. If False, add_option will apply to the toplevel parser
opt_group_header (str
@rtype tuple of (parser object, parser function) @returns the parser object to add options to and the function by which you can add arguments
) - Name of OptionGroup (SDOP) or argument group (argparse) to add options under

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=None, group_options=True)

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

add_jobcontrol_diagnostic_options(parser, options=None, group_options=True)

create_argument_parser(*args, **kwargs)

_get_option_container(parser, group_header=None)

print_version(version_source=`''`)

version_string(version_source=`''`)

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