osbuild: describe the result Manifest.build() and Stage.run()

This commit adds mypy annotations and a docstring to make it
easier to trace the result value of an osbuild run.

osbuild/pipeline.py

@@ -4,7 +4,7 @@
 import json
 import os
 from fnmatch import fnmatch
-from typing import Dict, Generator, Iterable, Iterator, List, Optional
+from typing import Any, Dict, Generator, Iterable, Iterator, List, Optional
 
 from . import buildroot, host, objectstore, remoteloop
 from .api import API
@@ -142,7 +142,7 @@ def prepare_arguments(self, args, location):
         with open(location, "w", encoding="utf-8") as fp:
             json.dump(args, fp)
 
-    def run(self, tree, runner, build_tree, store, monitor, libdir, debug_break="", timeout=None):
+    def run(self, tree, runner, build_tree, store, monitor, libdir, debug_break="", timeout=None) -> BuildResult:
         with contextlib.ExitStack() as cm:
 
             build_root = buildroot.BuildRoot(build_tree, runner.path, libdir, store.tmp)
@@ -161,15 +161,15 @@ def run(self, tree, runner, build_tree, store, monitor, libdir, debug_break="",
             inputs_tmpdir = os.path.join(tmpdir, "inputs")
             os.makedirs(inputs_tmpdir)
             inputs_mapped = "/run/osbuild/inputs"
-            inputs = {}
+            inputs: Dict[Any, Any] = {}
 
             devices_mapped = "/dev"
-            devices = {}
+            devices: Dict[Any, Any] = {}
 
             mounts_tmpdir = os.path.join(tmpdir, "mounts")
             os.makedirs(mounts_tmpdir)
             mounts_mapped = "/run/osbuild/mounts"
-            mounts = {}
+            mounts: Dict[Any, Any] = {}
 
             os.makedirs(os.path.join(tmpdir, "api"))
             args_path = os.path.join(tmpdir, "api", "arguments")
@@ -210,17 +210,17 @@ def run(self, tree, runner, build_tree, store, monitor, libdir, debug_break="",
 
             ipmgr = InputManager(mgr, storeapi, inputs_tmpdir)
             for key, ip in self.inputs.items():
-                data = ipmgr.map(ip, store)
-                inputs[key] = data
+                data_inp = ipmgr.map(ip, store)
+                inputs[key] = data_inp
 
             devmgr = DeviceManager(mgr, build_root.dev, tree)
             for name, dev in self.devices.items():
                 devices[name] = devmgr.open(dev)
 
             mntmgr = MountManager(devmgr, mounts_tmpdir)
             for key, mount in self.mounts.items():
-                data = mntmgr.mount(mount)
-                mounts[key] = data
+                data_mnt = mntmgr.mount(mount)
+                mounts[key] = data_mnt
 
             self.prepare_arguments(args, args_path)
 
@@ -470,10 +470,20 @@ def depsolve(self, store: ObjectStore, targets: Iterable[str]) -> List[str]:
 
         return list(map(lambda x: x.name, reversed(build.values())))
 
-    def build(self, store, pipelines, monitor, libdir, debug_break="", stage_timeout=None):
+    def build(self, store, pipelines, monitor, libdir, debug_break="", stage_timeout=None) -> Dict[str, Any]:
+        """Build the manifest
+
+        Returns a dict of string keys that contains the overall
+        "success" and the `BuildResult` of each individual pipeline.
+
+        The overall success "success" is stored as the string "success"
+        with the bool result and the build pipelines BuildStatus is
+        stored under the pipelines ID string.
+        """
         results = {"success": True}
 
         for pl in map(self.get, pipelines):
+            assert pl is not None
             res = pl.run(store, monitor, libdir, debug_break, stage_timeout)
             results[pl.id] = res
             if not res["success"]: