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.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.utils.cmdline.Options(value)

Bases: enum.Enum

An enumeration.

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

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