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 an info() and a 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 from which driver is called 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) -> None:
    """Implement script protocol.

    The most common usage is to call `driver()` from a script
    that defines an `info()` and a `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 from which `driver` is called
        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