driverclient 0.2.0__tar.gz → 0.2.1__tar.gz

{driverclient-0.2.0 → driverclient-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.0
+Version: 0.2.1
 Summary: Driver Server client with an embeddable connector for config injection at runtime.
 Project-URL: Homepage, https://example.com/driverclient
 Author-email: Raja Sanaullah <sanaullah@99technologies.com>
@@ -110,6 +110,32 @@ Each `ClientEvent` (frozen dataclass, `ev.to_dict()` for transport) has:
 `phase` and `status` are a fixed, documented vocabulary — this is the interface
 a GUI binds to; treat changes to it as an API change.
 
+#### Reboots (the client does not reboot — the caller decides)
+
+The client is **stateless and single-shot**: it installs/captures in one pass and
+returns. It never reboots and keeps no state across reboots. When a driver
+installs but needs a reboot to take effect (installer exit code `3010`/`1641`),
+that is reported as **success with a reboot flag**, not a failure:
+
+- `InstallResult.reboot_required` / `AutomateResult.reboot_required` → `bool`
+- the per-driver `install` event carries `data["reboot_required"]`
+
+The embedding app owns the reboot + resume loop. Typical convergence:
+
+```python
+result = client.run("automate", on_event=cb)
+if result.reboot_required:
+    persist_state(); schedule_resume(); reboot()      # then run "automate" again
+elif not result.made_progress:
+    proceed_to_next_step()                             # nothing new + no reboot = converged
+```
+
+`AutomateResult.made_progress` is `True` when the pass installed or captured
+anything, so `not made_progress and not reboot_required` means the machine has
+converged. Drivers for devices that only appear *after* a reboot are picked up on
+the next pass; run a `capture-missing` / `wu-full` pass post-reboot to catch
+packages Windows Update only stages during the reboot.
+
 > Events are emitted on whatever thread the op is running on — and the parallel
 > download/export/upload pools mean some events arrive on **worker threads**. The
 > Qt pattern below (queued cross-thread signals) is safe regardless.

{driverclient-0.2.0 → driverclient-0.2.1}/README.md

@@ -94,6 +94,32 @@ Each `ClientEvent` (frozen dataclass, `ev.to_dict()` for transport) has:
 `phase` and `status` are a fixed, documented vocabulary — this is the interface
 a GUI binds to; treat changes to it as an API change.
 
+#### Reboots (the client does not reboot — the caller decides)
+
+The client is **stateless and single-shot**: it installs/captures in one pass and
+returns. It never reboots and keeps no state across reboots. When a driver
+installs but needs a reboot to take effect (installer exit code `3010`/`1641`),
+that is reported as **success with a reboot flag**, not a failure:
+
+- `InstallResult.reboot_required` / `AutomateResult.reboot_required` → `bool`
+- the per-driver `install` event carries `data["reboot_required"]`
+
+The embedding app owns the reboot + resume loop. Typical convergence:
+
+```python
+result = client.run("automate", on_event=cb)
+if result.reboot_required:
+    persist_state(); schedule_resume(); reboot()      # then run "automate" again
+elif not result.made_progress:
+    proceed_to_next_step()                             # nothing new + no reboot = converged
+```
+
+`AutomateResult.made_progress` is `True` when the pass installed or captured
+anything, so `not made_progress and not reboot_required` means the machine has
+converged. Drivers for devices that only appear *after* a reboot are picked up on
+the next pass; run a `capture-missing` / `wu-full` pass post-reboot to catch
+packages Windows Update only stages during the reboot.
+
 > Events are emitted on whatever thread the op is running on — and the parallel
 > download/export/upload pools mean some events arrive on **worker threads**. The
 > Qt pattern below (queued cross-thread signals) is safe regardless.

{driverclient-0.2.0 → driverclient-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "driverclient"
-version = "0.2.0"
+version = "0.2.1"
 description = "Driver Server client with an embeddable connector for config injection at runtime."
 readme = "README.md"
 requires-python = ">=3.10"

{driverclient-0.2.0 → driverclient-0.2.1}/src/driverclient/__init__.py

@@ -25,7 +25,7 @@ from driverclient.main import run as _run
 
 __all__ = ["DriverClient", "ClientEvent"]
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 
 class DriverClient:

{driverclient-0.2.0 → driverclient-0.2.1}/src/driverclient/ops/automate.py

@@ -32,6 +32,22 @@ class AutomateResult:
     wu:              CaptureResult | None = None
     duration_s:      int           = 0
 
+    @property
+    def reboot_required(self) -> bool:
+        """True if this pass installed a driver that needs a reboot to take effect."""
+        return bool(self.install and self.install.reboot_required)
+
+    @property
+    def made_progress(self) -> bool:
+        """
+        True if this pass installed and/or captured anything. When this is
+        False and reboot_required is False, the machine has converged — the
+        caller can stop looping and move to the next step.
+        """
+        installed = self.install.ok_count if self.install else 0
+        captured  = self.wu.submitted if self.wu else 0
+        return bool(installed or captured)
+
 
 def run_automation() -> AutomateResult:
     cfg    = get()
@@ -106,6 +122,9 @@ def _summary(r: AutomateResult) -> None:
     events.done("done", f"  Duration : {r.duration_s}s", duration_s=r.duration_s)
     events.done("done", f"  Installed: {inst.ok_count} ok  {inst.fail_count} failed",
                 installed_ok=inst.ok_count, installed_failed=inst.fail_count)
+    if inst.reboot_required:
+        events.done("done", "  Reboot   : REQUIRED (a driver needs a reboot to take effect)",
+                    reboot_required=True)
     if r.wu and r.wu.wu_triggered:
         events.done("done",
                     f"  WU       : {wu.submitted} captured  {wu.still_missing} still missing",

{driverclient-0.2.0 → driverclient-0.2.1}/src/driverclient/ops/install.py

@@ -33,13 +33,19 @@ _CATEGORY_ORDER: dict[str, int] = {
     "network": 3, "display": 5, "audio": 6, "other": 10,
 }
 
+# Installer exit codes that mean "succeeded, but a reboot is required".
+#   3010 = ERROR_SUCCESS_REBOOT_REQUIRED (pnputil / MSI / most installers)
+#   1641 = ERROR_SUCCESS_REBOOT_INITIATED
+_REBOOT_CODES: frozenset[int] = frozenset({3010, 1641})
+
 
 @dataclass
 class DriverResult:
-    binding_id:  str
-    success:     bool
-    error:       str = ""
-    duration_ms: int = 0
+    binding_id:      str
+    success:         bool
+    error:           str  = ""
+    duration_ms:     int  = 0
+    reboot_required: bool = False   # installed OK but needs a reboot (pnputil 3010)
 
 
 @dataclass
@@ -53,6 +59,11 @@ class InstallResult:
     @property
     def fail_count(self) -> int: return len(self.install_failed)
 
+    @property
+    def reboot_required(self) -> bool:
+        """True if any successfully-installed driver reported reboot-required."""
+        return any(r.reboot_required for r in self.installed_ok)
+
 
 def resolve_and_install(force: bool = False) -> InstallResult:
     """
@@ -83,9 +94,12 @@ def resolve_and_install(force: bool = False) -> InstallResult:
 
     _confirm(result.trace_id, installed_ok, install_failed, cfg)
 
+    reboot_required = any(r.reboot_required for r in installed_ok)
+    reboot_tag = "  — reboot required" if reboot_required else ""
     events.done("install",
-                f"[install] Done — {len(installed_ok)} ok  {len(install_failed)} failed",
-                total=len(all_results), ok=len(installed_ok), failed=len(install_failed))
+                f"[install] Done — {len(installed_ok)} ok  {len(install_failed)} failed{reboot_tag}",
+                total=len(all_results), ok=len(installed_ok), failed=len(install_failed),
+                reboot_required=reboot_required)
     for r in install_failed:
         events.error("install", f"  ✗ {r.binding_id}: {r.error}",
                      binding_id=r.binding_id, error=r.error)
@@ -173,12 +187,15 @@ def _process_completed(
         return DriverResult(binding_id=bid, success=False, error="download_failed")
 
     t0 = time.monotonic()
-    ok, err = _install_driver(driver, dest, cfg)
+    ok, err, reboot = _install_driver(driver, dest, cfg)
     dur = int((time.monotonic() - t0) * 1000)
-    line = f"  {'✓' if ok else '✗'} [{cat}] {bid}  ({dur}ms)"
+    tag = " (reboot required)" if reboot else ""
+    line = f"  {'✓' if ok else '✗'} [{cat}] {bid}  ({dur}ms){tag}"
     emit = events.ok if ok else events.error
-    emit("install", line, binding_id=bid, category=cat, duration_ms=dur, error=err)
-    return DriverResult(binding_id=bid, success=ok, error=err, duration_ms=dur)
+    emit("install", line, binding_id=bid, category=cat, duration_ms=dur,
+         error=err, reboot_required=reboot)
+    return DriverResult(binding_id=bid, success=ok, error=err,
+                        duration_ms=dur, reboot_required=reboot)
 
 
 def _download_driver(driver: dict, base: Path, repo_url: str,
@@ -208,50 +225,65 @@ def _level_label(level: int) -> str:
 
 # ── Driver installation ─────────────────────────────────────────────────────────
 
-def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, str]:
+def _classify(returncode: int, err_text: str = "") -> tuple[bool, str, bool]:
+    """
+    Map an installer exit code to (success, error, reboot_required).
+
+    0                  -> success, no reboot
+    3010 / 1641        -> success, reboot required (NOT a failure)
+    anything else      -> failure, carry err_text
+    """
+    if returncode == 0:
+        return True, "", False
+    if returncode in _REBOOT_CODES:
+        return True, "", True
+    return False, err_text, False
+
+
+def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, str, bool]:
     install_type = driver.get("install_type", "inf_silent")
 
     try:
         if install_type == "inf_silent":
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
-                return False, "No INF file found"
+                return False, "No INF file found", False
             r = subprocess.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install", "/subdirs"],
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return r.returncode == 0, r.stdout[:200] if r.returncode != 0 else ""
+            return _classify(r.returncode, r.stdout[:200])
 
         if install_type == "exe_silent":
             exe_files = list(driver_dir.glob("*.exe"))
             if not exe_files:
-                return False, "No EXE file found"
+                return False, "No EXE file found", False
             flags = driver.get("install_flags", "/S")
             r = subprocess.run(
                 [str(exe_files[0])] + flags.split(),
                 capture_output=True,
                 timeout=cfg["timeout_install"],
             )
-            return r.returncode == 0, ""
+            return _classify(r.returncode)
 
         if install_type == "firmware_flash":
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
-                return False, "No firmware INF"
+                return False, "No firmware INF", False
             r = subprocess.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install"],
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return r.returncode == 0, ""
+            return _classify(r.returncode)
 
     except subprocess.TimeoutExpired:
-        return False, "Install timed out"
+        return False, "Install timed out", False
     except Exception as e:
-        return False, str(e)
+        return False, str(e), False
 
-    return False, f"Unknown install_type: {install_type}"
+    return False, f"Unknown install_type: {install_type}", False
 
 
 # ── Confirm ─────────────────────────────────────────────────────────────────────