schrodinger.utils.cmdline module

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

  1. 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.

  2. 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.

  3. 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.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.utils.cmdline.DelegatingIndentedHelpFormatter(indent_increment=2, max_help_position=24, width=None, short_first=1)

Bases: optparse.IndentedHelpFormatter

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

format_option_strings(option)

Return a formatted option string.

Allow the provided option to alter the string if it has a process_option_strings() method.

class schrodinger.utils.cmdline.SingleDashOption(*args, **kwargs)

Bases: optparse.Option

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

process_option_strings(formatted_option_strings)

Post-process the provided formatted options string to replace the translated double dash options with their original single dash specifications.

class schrodinger.utils.cmdline.SingleDashOptionParser(*args, **kwargs)

Bases: optparse.OptionParser

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

Note that this class can therefore not be used for clustering short options - i.e. “-rf” will be interpreted as a long option “rf”, not the short options “-r” and “-f”.

get_option(opt_str)

Return the Option instance with the option string opt_str, or None if no options have that string.

has_option(option)
parse_args(args=None, values=None, ignore_unknown=False)
print_usage(file : file = stdout)

Print the usage message for the current program (self.usage) to ‘file’ (default stdout). Any occurence of the string “%prog” in self.usage is replaced with the name of the current program (basename of sys.argv[0]). Does nothing if self.usage is empty or not defined.

remove_option(opt_str)

Remove the Option with the option string opt_str.

schrodinger.utils.cmdline.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
schrodinger.utils.cmdline.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 option is deprecated. Use HOST option instead.

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 (bool) – If True then group the added options (via an optparse.OptionGroup) in the help message under the header ‘Job Control Options’.
schrodinger.utils.cmdline.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.
Parameters:
  • parser (SingleDashOptionParser or ArgumentParser) – Instance of this module’s SingleDashOptionParser or insance of argparseArgumentParser.
  • 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 ‘Standard Options’.
  • group_options – bool
  • default_retries – The default number of retries to use (only applies is RETRIES is included in options)
  • default_retries – integer
schrodinger.utils.cmdline.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.

Parameters:version_source (unicode) – A string containing a CVS Revision string like $Revision: 1.26 $. If not specified, it uses the Schrodinger python version number.
schrodinger.utils.cmdline.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.
schrodinger.utils.cmdline.print_version(version_source='')

Print the script version and exit.

Parameters:version_source (str) – The string to search for a Revision tag.
schrodinger.utils.cmdline.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.