Documentation, comments and small changes

source/build_network.py

@@ -29,13 +29,15 @@ import subprocess
 import sys
 from typing import Optional, Sequence, Tuple, Union
 
-from topology_loader import TopologyLoadError, load
-from topology_parser import TopologyParseError
+from topology_loader import TopologyLoadError, load_topology
+from topology_parser import TopologyParseError, parse_topology
 from topology_plan import ExecutionPlan, TopologyPlanError, plan
 from topology_renderer import render_python
 from topology_validator import TopologyValidationError, validate
 
 
+# ============================ Types and errors ============================
+
 PathLike = Union[str, Path]
 
 
@@ -76,6 +78,8 @@ class EnvironmentReport:
         return all(item.available for item in self.requirements)
 
 
+# =========================== Environment checks ===========================
+
 def _check_python_module(name: str, install_hint: str) -> EnvironmentRequirement:
     """Check whether one Python module is importable.
 
@@ -193,6 +197,8 @@ def check_environment() -> EnvironmentReport:
     return EnvironmentReport(requirements=tuple(requirements))
 
 
+# =================== Compilation and artifact execution ===================
+
 def compile_topology(path: PathLike) -> Tuple[ExecutionPlan, str]:
     """Compile one topology file into a plan and executable Python source.
 
@@ -212,7 +218,7 @@ def compile_topology(path: PathLike) -> Tuple[ExecutionPlan, str]:
             complete execution plan.
     """
 
-    topology = load(path)
+    topology = parse_topology(load_topology(path))
     validate(topology)
     execution_plan = plan(topology)
     source = render_python(execution_plan)
@@ -241,7 +247,7 @@ def write_generated_python(source: str, path: PathLike) -> Path:
         path: Destination path for the generated artifact.
 
     Returns:
-        Resolved destination Path.
+        Destination Path, remaining relative if the supplied path is relative.
 
     Raises:
         BuildNetworkError: If the artifact cannot be written.
@@ -294,6 +300,8 @@ def execute_generated_python(path: PathLike) -> int:
     return completed.returncode
 
 
+# ================== Command-line reporting and arguments ==================
+
 def _print_environment_report(report: EnvironmentReport) -> None:
     """Print an environment report from the command-line layer.
 
@@ -350,6 +358,8 @@ def _build_argument_parser() -> argparse.ArgumentParser:
     return parser
 
 
+# ======================== Command-line entry point ========================
+
 def main(argv: Optional[Sequence[str]] = None) -> int:
     """Run the coordinator command-line interface.