schrodinger.utils.cmdline module¶

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

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 ArgumentParser.)

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.

class schrodinger.utils.cmdline.Options(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: enum.Enum

DEBUG = 1¶

DEBUGGER = 2¶

DRIVERHOST = 3¶

HOST = 4¶

HOSTLIST = 5¶

HOSTWITHTHREADS = 6¶

HOSTWITHSUBJOBS = 7¶

JOBNAME = 8¶

LOCAL = 9¶

NICE = 10¶

NJOBS = 11¶

NSTRUCTS = 12¶

NOJOBID = 13¶

NOLAUNCH = 14¶

NOLOCAL = 15¶

OPLSDIR = 16¶

RETRIES = 17¶

RESTART = 18¶

SAVE = 19¶

STRICT = 20¶

SUBHOST = 21¶

TMPDIR = 22¶

VIEWNAME = 23¶

WAIT = 24¶

class schrodinger.utils.cmdline.RequireArgValue(option_strings, dest, nargs=None, const=None, **kwargs)¶

Bases: argparse.Action

For arguments of the form -flag <value>, this class stores <value> at the appropriate destination, while prohibiting <value> from being an empty or pure whitespace string. This class may be used as follows for a string-valued argument:

parser.add_argument(‘-out’, action=RequireArgValue, help=’Output File.’)

It may also be used for positional arguments, numeric arguments, and arguments with choices. However, in the case of numeric arguments, an empty/whitespace value will be rejected before reaching this class since such a value is not numeric. If choices are supplied, an empty/whitespace value will reach this class and be rejected only if that value is one of the allowed choices, in which case this class isn’t appropriate.

__init__(option_strings, dest, nargs=None, const=None, **kwargs)¶

class schrodinger.utils.cmdline.RestrictedArgRange(lower_limit, upper_limit, lower_inclusive=True, upper_inclusive=True)¶

Bases: object

Provides generalized range checking suitable for the add_argument function of argparser.ArgumentParser. For example:

parser = argparse.ArgumentParser()
parser.add_argument('-dihed', type=float, metavar='<degrees>',
                    choices=[RestrictedArgRange(-180.0, 180.0)],
                    help='Dihedral angle in degrees.')
parser.add_argument('-path', type=int, metavar='<length>',
                    choices=[RestrictedArgRange(1, None)],
                    help='Non-zero path length in bonds.')

More general usage is as follows:

legal_range = RestrictedArgRange(-180.0, 180.0)
dihed = 120.0
if dihed in legal_range:
    print('Dihedral is legal')

__init__(lower_limit, upper_limit, lower_inclusive=True, upper_inclusive=True)¶

Constructor taking lower and upper limits and whether those limits are inclusive. Use None for a limit that doesn’t exist.

Parameters

lower_limit (Any numeric type or None) – Lower limit of legal range
upper_limit (Any numeric type or None) – Upper limit of legal range
lower_inclusive (bool) – True if lower limit is inclusive
upper_inclusive (bool) – True if upper limit is inclusive

__contains__(value)¶: The ‘in’ operator for the provided value.

schrodinger.utils.cmdline.main_wrapper(main: Callable, *args, exit_on_return: bool = True, **kwargs)¶

Wrap ‘main’ functions for improved user interaction. This should be used for functions invoked via __main__.

This function will call the provided ‘main’ function while installing an exception handler that saves tracebacks to a file (unless running in a development environment). KeyboardInterrupt and BrokenPipeError exceptions are handled silently and simply exit with code 1.

Parameters

main – The function that should be called.
exit_on_return – when this is set to True (default), this function will explicitly invoke a system exit once main returns.
args – Additional positional arguments will be passed to the provided main function when it is called.

schrodinger.utils.cmdline.print_version(version_source: str = '')¶

Print the script version and exit.

Parameters: version_source – The string to search for a Revision tag.

schrodinger.utils.cmdline.add_jobcontrol_options(parser: argparse.ArgumentParser, options: Optional[List[schrodinger.utils.cmdline.Options]] = None, group_options: bool = True)¶

Adds common Job Control options to an argparse.ArgumentParser instance.

The options are specified as a list of module enums.

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 = argparse.ArgumentParser()
cmdline.add_jobcontrol_options(parser)
args = parser.parse_args()

Parameters

parser – a parser instance
options – List of module enums that indicate what options to add to the parser. If not specified, the default options only include HOST.
group_options – If True, options are added in a group in help under the header ‘Job Control Options’.

schrodinger.utils.cmdline.add_standard_options(parser: argparse.ArgumentParser, options: Optional[List[schrodinger.utils.cmdline.Options]] = None, group_options: bool = True, default_retries: Optional[int] = None)¶

Adds standard options to an 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 mutually 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 mutually exclusive.

Example usage:

parser = argparse.ArgumentParser()
cmdline.add_standard_options(parser)
args = cmdline.parse_standard_options(parser, args)

Parameters

parser – a parser instance
options – List of module enums that indicate what options to add to the parser.
group_options – If True then the added options are added as a group in the help message under the header ‘Standard Options’.
default_retries – The default number of retries to use (only applies is RETRIES is included in options)

schrodinger.utils.cmdline.get_opls_dir() → Optional[str]¶

Return the current OPLS dir, if any. Note that by “current” we mean that calling this method in a job frontend (e.g. get_job_spec_from_args) will return the frontend OPLS dir, whereas calling it in a backend (e.g. main) will return the backend OPLS dir.

toplevel.py consumes -OPLSIDIR, sets it to an environment variable, and strips it from sys.argv. Use this function to retrieve the OPLS dir if it’s needed in a script.

schrodinger.utils.cmdline.create_argument_parser(*args, **kwargs)¶

Prefer use of argparse.ArgumentParser directly.

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 (str) – A string containing a CVS Revision string like $Revision: 1.26 $. If not specified, it uses the Schrodinger python version number.