wp.runner: Document & convert to using pathlib.Path

README.md

@@ -71,23 +71,7 @@ They can either be modified directly or copied and then given to the runner by p
 ```
 workload-processor run agenda.yaml baseline
 ```
-
-### Relevant help section
-
-```
-usage: WA Workload Processor run [-h] [-d DIR] [-n] [-f] [-a] workload [tag]
-
-positional arguments:
-  workload            Workload name or agenda file path
-  tag                 Tag for the run
-
-optional arguments:
-  -h, --help          show this help message and exit
-  -d DIR, --dir DIR   Output directory
-  -n, --no-module     Don't try to load the Lisa kernel module
-  -f, --force         Overwrite output directory if it exists
-  -a, --auto-process  Auto process after the run completes
-```
+For more information, consult `wp.runner`.
 
 ### workload-automation plugins
 

wp/cli.py

@@ -42,7 +42,7 @@ def device(args):
 
 
 def main():
-    parser = argparse.ArgumentParser(prog='WA Workload Processor')
+    parser = argparse.ArgumentParser()
     subparsers = parser.add_subparsers(required=True, dest='subparser_name', title='subcommands')
     parser.add_argument('-v', '--verbose', action='store_true', help="Verbose output, including lisa debug logging")
 

wp/runner.py

@@ -1,10 +1,36 @@
-import sys
+"""
+Workload runner module. Effectively a proxy for `workload-automation` that makes sure the created workloads are
+compatible with the rest of workload-processor.
+
+Intended to be accessed through the CLI as follows:
+```
+usage: workload-processor run [-h] [-d DIR] [-n] [-f] [-a] workload [tag]
+
+positional arguments:
+  workload            Workload name or agenda file path
+  tag                 Tag for the run
+
+optional arguments:
+  -h, --help          show this help message and exit
+  -d DIR, --dir DIR   Output directory
+  -n, --no-module     Don't try to load the Lisa kernel module
+  -f, --force         Overwrite output directory if it exists
+  -a, --auto-process  Auto process after the run completes
+```
+
+The module can still normally be used through Python.
+"""
+
 import os
+import sys
 import time
 import subprocess
 import logging as log
 import confuse
 
+from typing import Optional
+
+from pathlib import Path
 from datetime import date
 from ppadb.client import Client as AdbClient
 
@@ -13,14 +39,30 @@
 from wp.constants import AGENDAS_PATH, SUPPORTED_WORKLOADS, APP_NAME
 
 
+# TODO: use devlib target to make this platform-agnostic
 class WorkloadRunner:
-    def __init__(self, output_dir, config=None):
+    """The runner class that performs setup and dispatches the run to `workload-automation`."""
+
+    def __init__(self, output_dir: Optional[str], config: Optional[confuse.Configuration] = None):
+        """
+        Initialise the runner
+
+        :param output_dir: Output directory for the run to be stored (defaults to putting the run under CWD)
+        :param config: `Confuse` config object
+        :raises TargetStableError: When no target devices are found
+        """
         self.config = confuse.Configuration(APP_NAME, __name__) if config is None else config
-        self.output_dir = output_dir
+        """`Confuse` configuration handle"""
+        self.output_dir = Path(output_dir) if output_dir else None
+        """Output directory for the run to be stored"""
         self.force = self.config['force'].get(False)
+        """Overwrite the run output directory if it already exists"""
         self.adb_client = AdbClient(host=self.config['host']['adb_host'].get(str),
                                     port=int(self.config['host']['adb_port'].get(int)))
+        """ADB client handle"""
 
+        self.device = None
+        """ADB device handle"""
         try:
             self.device = self.adb_client.devices()[0]
         except IndexError:
@@ -45,32 +87,40 @@ def __init__(self, output_dir, config=None):
             return
 
         # insert the lisa module
-        target_conf_path = os.path.expanduser(self.config['target']['target_conf'].get(str))
+        target_conf_path = Path(self.config['target']['target_conf'].get(str)).expanduser()
         log.debug(f'Calling lisa-load-kmod with {target_conf_path}')
         log_level = 'debug' if log.getLogger().isEnabledFor(log.DEBUG) else 'info'
-        cmd = ['lisa-load-kmod', '--log-level', log_level, '--conf', target_conf_path]
+        cmd = ['lisa-load-kmod', '--log-level', log_level, '--conf', str(target_conf_path)]
         process = subprocess.Popen(cmd, stdout=subprocess.PIPE)
         for c in iter(lambda: process.stdout.read(1), b""):
             sys.stdout.buffer.write(c)
 
-    def run(self, workload, tag):
+    def run(self, workload: str, tag: str) -> Path:
+        """
+        Run workload `workload` with tag `tag`.
+
+        :param workload: Either a name of a predefined workload (consult `wp.constants.SUPPORTED_WORKLOADS`)
+        or a path to a `workload-automation` agenda.
+        :param tag: Tag for the run, e.g. `baseline`.
+        :return: Returns the path to where the run was saved on completion.
+        """
         if workload.endswith('yaml') or workload.endswith('yml'):
             agenda_path = workload
         elif workload in SUPPORTED_WORKLOADS:
-            agenda_path = os.path.join(AGENDAS_PATH, f"agenda_{workload}.yaml")
+            agenda_path = Path(AGENDAS_PATH) / f"agenda_{workload}.yaml"
         else:
             log.error(f"workload or agenda {workload} not supported")
             return None
 
-        agenda_parsed = load_yaml(agenda_path)
+        agenda_parsed = load_yaml(str(agenda_path))
         workload_name = agenda_parsed['workloads'][0]['name']
         iterations = agenda_parsed['config']['iterations']
         day_month = date.today().strftime("%d%m")
 
         if not self.output_dir:
-            self.output_dir = os.path.join(os.getcwd(), f"{workload_name}_{tag}_{iterations}_{day_month}")
+            self.output_dir = Path(os.getcwd()) / f"{workload_name}_{tag}_{iterations}_{day_month}"
 
-        cmd = ["wa", "run", str(agenda_path), "-d", self.output_dir]
+        cmd = ["wa", "run", str(agenda_path), "-d", str(self.output_dir)]
         if self.force:
             cmd.append("-f")