schrodinger.application.desmond.packages.cui module

Common command-line interface for Desmond scripts

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.desmond.packages.cui.info(message)

schrodinger.application.desmond.packages.cui.warn(message)

schrodinger.application.desmond.packages.cui.error(message, exit_code=1, should_exit=True)

schrodinger.application.desmond.packages.cui.all_fnames_in_dir(dname)

Returns all regular files under the given directory, including those in subdirectories.

Parameters:dname (str) – Path of the directory Return type:list of str

schrodinger.application.desmond.packages.cui.jc_reg_input(builder, fname)

Register an input file for jobcontrol to transfer.

Parameters:

• builder (launchapi.JobSpecificationArgsBuilder) – You can get a builder by calling CommandLine.get_job_spec.
• fname (str) – Input file name to be transferred by jobcontrol. The file can be a directory, and in this case all regular files under this directory will be transferred. If fname contains a relative path, the relative path will be preserved on the host.

schrodinger.application.desmond.packages.cui.jc_reg_output(builder, fname)

Preregister an output file for jobcontrol to transfer.

Parameters:

• builder (launchapi.JobSpecificationArgsBuilder) – You can get a builder by calling CommandLine.get_job_spec.
• fname (str) – Input file name to be transferred by jobcontrol. The file can be a directory.

schrodinger.application.desmond.packages.cui.jc_backend_reg_output(fname)

Register (on the fly) an output file for jobcontrol to transfer.

Parameters:fname (str) – Output file name to be transferred by jobcontrol. The file can be a directory.

schrodinger.application.desmond.packages.cui.parse_slice(s)

Return a slice object derived from the given string s, in format of ‘i’, ‘start:end’, or ‘start:end:step’.

schrodinger.application.desmond.packages.cui.validate_and_enclose_asl(value, allow_empty=False)

class schrodinger.application.desmond.packages.cui.LazyParser(parser, priority=0)

Bases: object

Some argument parsers are so slow, e.g., the msys parser. We should avoid running them unless they are really needed. For example, when user just wants to see the help, or when there is another parsing errors which interrupts the execution of the command, there is no need to run these slow parsers. We use this class to delay slow parsers’ running.

__init__(parser, priority=0)

Parameters:

• parser (Callable object) – It should take a string argument, parse the string, and return the resultant object.
• priority (int: 0-9) – Specify the priority of parsing. High numbered object will be parsed earlier.

parse()

Calls the actual parser on the cached string and returns the parsing result.

string

Return the original string from the command line.

priority

Return the priority of this parser.

Return type:int

__call__(string)

Just caches the string to be parsed, and returns this LazyParser object itself. The real parsing will be conducted when the parse method of this class is explicitly called.

__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.cui', '__doc__': "\n Some argument parsers are so slow, e.g., the msys parser. We should avoid\n running them unless they are really needed. For example, when user just\n wants to see the help, or when there is another parsing errors which\n interrupts the execution of the command, there is no need to run these\n slow parsers. We use this class to delay slow parsers' running.\n ", '__init__': <function LazyParser.__init__>, 'parse': <function LazyParser.parse>, 'string': <property object>, 'priority': <property object>, '__call__': <function LazyParser.__call__>, '__dict__': <attribute '__dict__' of 'LazyParser' objects>, '__weakref__': <attribute '__weakref__' of 'LazyParser' objects>})

__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.cui'

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

class schrodinger.application.desmond.packages.cui.CommandLine(spec=46, **kwargs)

Bases: argparse.ArgumentParser

Use this class to define common command line arguments such input cms file, input trajectory, output file base name, trajectory slicing option, and so on.

After calling parse_args method, you will have those arguments parsed properly, and you will get the cms.Cms object, the msys.System object, and the trajectory object (sliced properly), automatically.

You can use the spec argument to custom your command line interface. Examples:

1: spec = REQUIRE_MSYS_CMS + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ # This will give you the following: # cms - First positional argument for cms input, and when it’s parsed, # you will get both msys and cms models. # trj - Second positional argument for trajectory input # out - Third positional argument for output base name # -slice-trj # - Option for slicing trajectory

2: spec = REQUIRE_CMS_ONLY + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ # Similar to the first example, but parsing the cms input file will return # only the cms model.

3: spec = REQUIRE_CMS_ONLY + OPTIONAL_TRJ + REQUIRE_OUT + SLICE_TRJ # This will give you the following: # cms - First positional argument for cms input, and when it’s parsed, # you will get the cms models. # out - Second positional argument for output base name # -trj - Option for trajectory input # -slice-trj # - Option for slicing trajectory

Other standard options:

-ref-mae	Reference geometry from given .mae or .cms file. After parsing, the ref_mae attribute will provide (structure.Structure, str), where the first element is the Structure object of the file and the second the file’s name. If this option is unspecified, the attribute’ value will be None. spec: REF_MAE
-ref-frame	Reference geometry from a trajectory frame. After parsing, the ref_frame attribute will provide (traj.Frame, int), where the first element is the specified frame and the second the index of the frame. If this option is overridden by -ref-mae, or if the trajectory is not provided, the attribute’s value will be None. spec: REF_FRAME
-output-trajectory-format
	Allow user to specify the output trajectory format. After parsing, the value of the out_trj_format attribute will be one of the contants defined within traj.Fmt. spec: OUT_TRJ_FORMAT

__init__(spec=46, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

del_argument(flag=None, dest=None)

Delete previously registered arguments that have the given flag or/and dest. No effects if such arguments are not found. Note: Positional arguments do NOT have flags. Specify dest to identify the positional argument to delete.

edit_argument_help(flag=None, dest=None, new_help='', edit='replace')

Sometimes we want to use a standard option with a custom help message. This method enables that.

Edit the help message of a previously registered argument as identified by the flag or/and dest argument. Note: Positional arguments do NOT have flags. Specify dest to identify the positional argument to edit.

Parameters:

• new_help (str, or cui.SUPPRESS) – The custom help message. If it is cui.SUPPRESS, the argument will NOT be shown in the help message.
• edit (str. Must be one of the following: "replace", "prepend", and "append" (case sensitive)) – Indicate how to edit the existing help message. “replace” - Replace the old help message with new_help. “append” - Append the old help message with new_help. “prepend” - Prepend the old help message with new_help.

Raises:

KeyError, if no argument is found.

parse_args(args=None, **kwargs)

get_job_spec(args=None, **kwargs)

Usage example:

In the python script:

def _get_cml():

cml = cui.CommandLine(spec=(cui.REQUIRE_MSYS_CMS + cui.REQUIRE_TRJ +

cui.SLICE_TRJ + cui.REQUIRE_OUT + cui.JC),

description=”my script”)

cml.add_argument(…) # Other application-specific options.

return cml

def get_job_spec_from_args(argv):

return _get_cml().get_job_spec(argv)[0]

The standard in-/output file options will be automatically registered for jobcontrol to transfer. If you have non-standard in-/output files, you can register them by yourself, for example:

def get_job_spec_from_args(argv):

_, builder, a = _get_cml().get_job_spec(argv) cui.jc_reg_input(builder, a[“input”]) cui.jc_reg_input(builder, “data/auxiliary_file_in_a_dir”) cui.jc_reg_output(builder, a[“another_output”]) return builder.getJobSpec()

Return type:(launchapi.JobSpecification, launchapi.JobSpecificationArgsBuilder, dict)

__class__

alias of builtins.type

__delattr__

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'schrodinger.application.desmond.packages.cui', '__doc__': "\n Use this class to define common command line arguments such input cms\n file, input trajectory, output file base name, trajectory slicing option,\n and so on.\n\n After calling `parse_args` method, you will have those arguments parsed\n properly, and you will get the `cms.Cms` object, the `msys.System` object,\n and the trajectory object (sliced properly), automatically.\n\n You can use the `spec` argument to custom your command line interface.\n Examples:\n\n 1:\n spec = REQUIRE_MSYS_CMS + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ\n # This will give you the following:\n # cms - First positional argument for cms input, and when it's parsed,\n # you will get both msys and cms models.\n # trj - Second positional argument for trajectory input\n # out - Third positional argument for output base name\n # -slice-trj\n # - Option for slicing trajectory\n\n 2:\n spec = REQUIRE_CMS_ONLY + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ\n # Similar to the first example, but parsing the cms input file will return\n # only the cms model.\n\n 3:\n spec = REQUIRE_CMS_ONLY + OPTIONAL_TRJ + REQUIRE_OUT + SLICE_TRJ\n # This will give you the following:\n # cms - First positional argument for cms input, and when it's parsed,\n # you will get the cms models.\n # out - Second positional argument for output base name\n # -trj - Option for trajectory input\n # -slice-trj\n # - Option for slicing trajectory\n\n Other standard options:\n -ref-mae Reference geometry from given .mae or .cms file. After parsing,\n the `.ref_mae` attribute will provide\n `(structure.Structure, str)`, where the first element is the\n `Structure` object of the file and the second the file's name.\n If this option is unspecified, the attribute' value will be\n `None`.\n spec: REF_MAE\n -ref-frame\n Reference geometry from a trajectory frame. After parsing, the\n `.ref_frame` attribute will provide `(traj.Frame, int)`, where\n the first element is the specified frame and the second the\n index of the frame. If this option is overridden by -ref-mae, or\n if the trajectory is not provided, the attribute's value will\n be `None`.\n spec: REF_FRAME\n -output-trajectory-format\n Allow user to specify the output trajectory format. After\n parsing, the value of the `.out_trj_format` attribute will be\n one of the contants defined within `traj.Fmt`.\n spec: OUT_TRJ_FORMAT\n ", '__init__': <function CommandLine.__init__>, 'del_argument': <function CommandLine.del_argument>, 'edit_argument_help': <function CommandLine.edit_argument_help>, '_parse_args_impl': <function CommandLine._parse_args_impl>, 'parse_args': <function CommandLine.parse_args>, 'get_job_spec': <function CommandLine.get_job_spec>})

__dir__() → list

default dir() implementation

__eq__

Return self==value.

__format__()

default object formatter

__ge__

Return self>=value.

__getattribute__

Return getattr(self, name).

__gt__

Return self>value.

__hash__

Return hash(self).

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__

Return self<=value.

__lt__

Return self<value.

__module__ = 'schrodinger.application.desmond.packages.cui'

__ne__

Return self!=value.

__new__()

Create and return a new object. See help(type) for accurate signature.

__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__()

Return repr(self).

__setattr__

Implement setattr(self, name, value).

__sizeof__() → int

size of object in memory, in bytes

__str__

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object (if defined)

add_argument(dest, ..., name=value, ...)

add_argument(option_string, option_string, …, name=value, …)

add_argument_group(*args, **kwargs)

add_mutually_exclusive_group(**kwargs)

add_subparsers(**kwargs)

convert_arg_line_to_args(arg_line)

error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

exit(status=0, message=None)

format_help()

format_usage()

get_default(dest)

parse_known_args(args=None, namespace=None)

print_help(file=None)

print_usage(file=None)

register(registry_name, value, object)

set_defaults(**kwargs)