stepup.core.script

Driver function to facilitate writing scripts that adhere to StepUp’s script protocol.

Warning

The script interface for calling user Python scripts from plan.py has been deprecated in favor of the new Call interface. You are encouraged to migrate your plan.py files to the new API. See the migration guide for a step-by-step walkthrough.

driver(obj=None)

Implement script protocol.

The most common usage is to call driver() from a script that defines info() and run() function, e.g.:

#!/usr/bin/env python3
from stepup.core.script import driver

def info():
    return {"inp": ["input.txt"], "out": ["output.txt"]}

def run(inp: str, out: str):
    with open(inp) as fh:
        text = fh.read()
    with open(out, "w") as fh:
        fh.write(text.upper())

if __name__ == "__main__":
    driver()

Parameters:

• obj (Any, default: None ) –

  When not provided, the namespace of the module where driver is defined will be searched for names like ‘info’ and ‘run’ to implement the script protocol. When an object is given as a parameter, its attributes are searched instead.

Source code in stepup/core/script.py

def driver(obj: Any = None):
    """Implement script protocol.

    The most common usage is to call `driver()` from a script
    that defines `info()` and `run()` function, e.g.:

    ```python
    #!/usr/bin/env python3
    from stepup.core.script import driver

    def info():
        return {"inp": ["input.txt"], "out": ["output.txt"]}

    def run(inp: str, out: str):
        with open(inp) as fh:
            text = fh.read()
        with open(out, "w") as fh:
            fh.write(text.upper())

    if __name__ == "__main__":
        driver()
    ```

    Parameters
    ----------
    obj
        When not provided, the namespace of the module where `driver` is defined
        will be searched for names like 'info' and 'run' to implement the script protocol.
        When an object is given as a parameter, its attributes are searched instead.
    """
    frame = inspect.currentframe().f_back
    script_path = Path(frame.f_locals["__file__"]).relpath()
    if obj is None:
        # Get the calling module and use it as obj
        module_name = frame.f_locals["__name__"]
        obj = sys.modules.get(module_name)
        if obj is None:
            raise ValueError(
                f"The driver must be called from an imported module, got {module_name}"
            )
    args = parse_args(script_path)
    wrapper = ScriptWrapper(obj, script_path)
    if args.cmd == "plan":
        _driver_plan(script_path, args, wrapper)
    elif args.cmd == "cases":
        _driver_cases(script_path, wrapper)
    elif args.cmd == "run":
        _driver_run(script_path, args, wrapper)
    else:
        raise NotImplementedError