improved logging

python_app/scripts/convert_legacy_preprocess_sets.py

@@ -34,6 +34,7 @@ S21_ONLY_TARGET_KINDS = {"s21_calibration", "s21_reference"}
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the legacy preprocess-set conversion CLI."""
     parser = argparse.ArgumentParser(
         description=(
             "Convert old preprocess-set storage from a legacy python_app/data tree into the "
@@ -59,6 +60,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _load_json(path: Path) -> dict[str, Any]:
+    """Read a JSON file and return its top-level object, rejecting non-object roots."""
     payload = json.loads(path.read_text(encoding="utf-8"))
     if not isinstance(payload, dict):
         raise ValueError(f"JSON root must be object: {path}")
@@ -66,6 +68,7 @@ def _load_json(path: Path) -> dict[str, Any]:
 
 
 def _read_combo_position(combo_payload: dict[str, Any], *, primary_key: str, alias_key: str) -> int:
+    """Return a switch position from a combo record, accepting the primary or alias key."""
     if primary_key in combo_payload:
         return int(combo_payload[primary_key])
     if alias_key in combo_payload:
@@ -74,16 +77,23 @@ def _read_combo_position(combo_payload: dict[str, Any], *, primary_key: str, ali
 
 
 def _combo_suffix(input_pos: int, output_pos: int) -> str:
+    """Return the per-combo array-name suffix (e.g. ``i0_o1``) used in legacy NPZ keys."""
     return f"i{input_pos}_o{output_pos}"
 
 
 def _load_array(arrays: Any, key: str, *, dtype: np.dtype[Any], label: str) -> np.ndarray:
+    """Return a flattened array of the given dtype from an NPZ mapping, by key."""
     if key not in arrays:
         raise KeyError(f"Missing {label} array '{key}' in NPZ archive")
     return np.asarray(arrays[key], dtype=dtype).reshape(-1)
 
 
 def _load_legacy_collection(meta_path: Path, npz_path: Path, *, target_kind: str) -> SweepCollection:
+    """Build a SweepCollection from a legacy meta/NPZ pair for the given target kind.
+
+    Reads per-combo frequency, S21 and (when present) S11 arrays. For S21-only target
+    kinds a missing S11 is filled with zeros; for any other kind a missing S11 is an error.
+    """
     meta = _load_json(meta_path)
     combos_payload = meta.get("combos")
     if not isinstance(combos_payload, list):
@@ -148,6 +158,11 @@ def _convert_one_set(
     meta_path: Path,
     overwrite: bool,
 ) -> None:
+    """Convert a single legacy set (meta + NPZ) and save it under the target kind.
+
+    Raises if the companion NPZ is missing, or if the destination already exists and
+    ``overwrite`` is False.
+    """
     set_name = meta_path.stem
     npz_path = meta_path.with_suffix(".npz")
     if not npz_path.exists():
@@ -168,6 +183,11 @@ def _convert_one_set(
 
 
 def main() -> int:
+    """Walk the legacy data tree, convert every recognized set, and print a summary.
+
+    Returns 0 on full success, 1 if any set failed to convert, or 2 if no convertible
+    sets were found.
+    """
     parser = _build_parser()
     args = parser.parse_args()