schrodinger.tasks.cmdline module¶

schrodinger.tasks.cmdline.make_main(task_source: Union[type, Callable[[list[str]], schrodinger.tasks.tasks.AbstractComboTask]], jobcontrol_options: list[schrodinger.utils.cmdline.Options] | None = None, customizer_func: Optional[Callable[[Dict[schrodinger.models.parameters.CompoundParam, schrodinger.tasks.cmdline._Argument]], None]] = None, auto_write_output: bool = False) → Callable[[], int]¶

Return a main function that can be used to run a combo task from the command line. Includes a dynamically created argument parser that is used to populate the task input when running the script. See make_parser_from_task_class for more information on the dynamically created parser.

Example usage:

main = cmdline.make_main(CounterComboJobTask)

if __name__ == '__main__':
    qapplication.run_application(main)

A customizer_func can optionally be supplied to customize the dynamically created argument parser:

def make_positional(args_by_subparam):
    start_arg = args_by_subparam[CounterComboJobTask.input.start]
    start_arg.makePositional()
    end_arg = args_by_subparam[CounterComboJobTask.input.end]
    end_arg.makePositional()

main = cmdline.make_main(
    CounterComboJobTask, customizer_func=make_positional)

if __name__ == '__main__':
    qapplication.run_application(main)

In order to completely customize the argument parser, a function can instead be passed as the first argument. This function must take in sys.argv and return a combo task instance that has not yet been run. For example:

def make_counter_combo_task(argv: list[str]) -> CounterComboJobTask:
    parser = argparse.ArgumentParser(description='Count from any number to 10')
    parser.add_argument('start', type=int)
    opts = parser.parse_args(argv[1:])
    task = CounterComboJobTask()
    task.input.start = opts.start
    task.input.end = 10
    return task

main = cmdline.make_main(make_counter_combo_task)

if __name__ == '__main__':
    qapplication.run_application(main)

Parameters

task_source – A task class or a function that can be called to create a task instance that should be run. If a task class is supplied, the framework dynamically creates an argument parser based on the task’s input. If a function is supplied, that function is called with sys.argv so that it may parse command line arguments as needed to create its task instance.
jobcontrol_options – Jobcontrol options to add to the the dynamically created argument parser. This may only be supplied when a task class is supplied as task_source.
customizer_func – An optional function that can customize the dynamically created argument parser for a task class. This may only be supplied when a task class is supplied as task_source. The function must take in a dictionary mapping input subparams to their corresponding cmdline._Argument instances and modify the arguments as needed.
auto_write_output – Whether to automatically write the task output to file.

schrodinger.tasks.cmdline.make_get_job_spec_from_args(task_source: Union[type, Callable[[list[str]], schrodinger.tasks.tasks.AbstractComboTask]], customizer_func: Optional[Callable[[Dict[schrodinger.models.parameters.CompoundParam, schrodinger.tasks.cmdline._Argument]], None]] = None) → Callable[[List[str]], launchapi.JobSpecification]¶

Create a get_job_spec_from_args based on the specified task class. Must be used in addition to make_main. See make_main for information on task_source and customizer_func. Example usage:

get_job_spec_from_args = cmdline.make_get_job_spec_from_args(CounterComboJobTask)

Parameters

task_source – A task class or a function that can be called to create a task instance that should be run. If a task class is supplied, the framework dynamically creates an argument parser based on the task’s input. If a function is supplied, that function is called with sys.argv so that it may parse command line arguments as needed to create its task instance.
customizer_func – An optional function that can customize the dynamically created argument parser for a task class. This may only be supplied when a task class is supplied as task_source. The function must take in a dictionary mapping input subparams to their corresponding cmdline._Argument instances and modify the arguments as needed.

Returns

a get_job_spec_from_args function

schrodinger.tasks.cmdline.add_task_options(parser: argparse.ArgumentParser) → None¶

Add all options required by the tasks framework code. This will add at least one suppressed mutually exclusive group, so this function should be called after all other arguments have been added to the parser. Otherwise, ArgumentParser will throw an incredibly opaque error.

Parameters: parser – The argument parser to which the task options should be added.

schrodinger.tasks.cmdline.make_parser_from_task_class(TaskClass: type, parser: argparse.ArgumentParser = None, jobcontrol_options: list[schrodinger.utils.cmdline.Options] | None = None, customizer_func: Optional[Callable[[Dict[schrodinger.models.parameters.CompoundParam, schrodinger.tasks.cmdline._Argument]], None]] = None) → argparse.ArgumentParser¶

Given a TaskClass, return a parser that accepts optional arguments for all input parameters.

The parser itself is a standard schrodinger parser (see schrodinger.utils.cmdline). The task class docstring is used for the parser description.

Each parser argument is constructed using the following information: - The name of the input param (all flags are optional by default). Nested subparams are delimited by ‘.’. - The type hint of the input param - The default value of the input param - The help string of the input param (must be in the input class docstring)

For example:

class MyTask(tasks.ComboJobTask):
    class Input(parameters.CompoundParam):
        coord: Coord
        label: str = 'default label'

parser = make_parser_from_task_class(MyTask)
opts = parser.parse_args(['-coord.x', '4', '-coord.y', '2'])
print(opts.coord.x)  # 4
print(opts.coord.y)  # 2
print(opts.label)    # 'default label' (Input.label default)

A customizer function can also be supplied to modify the arguments created from the task input:

def make_positional(args_by_subparam):
    label_arg = args_by_subparam[MyTask.input.label]
    label_arg.makePositional()

parser = make_parser_from_task_class(MyTask, customizer_func=make_positional)
opts = parser.parse_args(['foo'])
print(opts.coord.x)  # 0 (Input.coord.x default)
print(opts.coord.y)  # 0 (Input.coord.y default)
print(opts.label)    # 'foo'

Parameters

TaskClass – The task class to create a parser for.
parser – An optional parser to add arguments to. If not supplied, a parser will be created.
jobcontrol_options – Jobcontrol options to add to the the dynamically created argument parser.
customizer_func – An optional function that can be used to customize the arguments created from the task input. The function should take a dictionary mapping subparams to their corresponding _Argument instances.

schrodinger.tasks.cmdline.make_parser_from_task_class_dict(task_dict: Dict[str, type], customizer_dict: Dict[str, Callable[[Dict[schrodinger.models.parameters.CompoundParam, schrodinger.tasks.cmdline._Argument]], None]] = None) → argparse.ArgumentParser¶

Return a parser that has subparsers for each task in task_dict. See make_parser_from_task_class for details about how each subparser is populated. For example:

class FooTask(tasks.ComboJobTask):
    class Input(parameters.CompoundParam):
        foo: int

class BarTask(tasks.ComboJobTask):
    class Input(parameters.CompoundParam):
        bar: int

parser = make_parser_from_task_class_dict(
    {'run-foo': FooTask, 'run-bar': BarTask})
opts = parser.parse_args(['run-foo', '-foo', '4'])
if opts.task_class is FooTask:
    populate_foo_task(opts)
elif opts.task_class is BarTask:
    populate_bar_task(opts)
else:
    raise_error()

A dictionary mapping subparser names to customizer functions can also be passed to customize the arguments created from the task input.

Parameters

task_dict – A dictionary mapping subparser names to task classes.
customizer_dict – A dictionary mapping subparser names to customizer functions.

schrodinger.tasks.cmdline.make_task_from_parsed_args(TaskClass, parsed_args: argparse.Namespace) → schrodinger.tasks.tasks.AbstractComboTask¶

Return a task instance with input values set based on the parsed arguments.

Precondition: parsed_args must come from a parser made from make_parser_from_task_class.