driverclient 0.2.0__py3-none-any.whl

driverclient/ops/scan.py

@@ -0,0 +1,316 @@
+"""
+client/ops/scan.py — Local hardware scan.
+
+Enumerates all connected devices via pnputil (two parallel calls — one for
+HWIDs, one for class names), collects model profile via WMI, and resolves
+installed driver versions. Results are cached to ds_scan.json.
+
+Public API:
+    scan(force=False) -> ScanResult
+"""
+import json
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from driverclient import events
+from driverclient.config import get
+from driverclient.core.hardware import (
+    compute_fingerprint,
+    get_installed_versions,
+    get_model_profile,
+)
+
+
+@dataclass
+class Device:
+    instance_id:       str
+    device_name:       str
+    hwids:             list[str]
+    has_driver:        bool
+    installed_version: str = ""
+    class_name:        str = ""   # e.g. "System", "Net", "Display adapters"
+
+
+@dataclass
+class ScanResult:
+    machine_id:        str
+    vendor:            str
+    model:             str
+    friendly_model:    str
+    serial:            str
+    chassis_type:      str
+    os_build:          int
+    arch:              str
+    firmware_version:  str
+    devices:           list[Device]     = field(default_factory=list)
+    installed_versions: dict[str, str]  = field(default_factory=dict)
+    timestamp:         str              = ""
+
+    @property
+    def all_hwids(self) -> list[str]:
+        return [h for d in self.devices for h in d.hwids]
+
+    @property
+    def missing_driver(self) -> list[Device]:
+        return [d for d in self.devices if not d.has_driver]
+
+    @property
+    def has_driver(self) -> list[Device]:
+        return [d for d in self.devices if d.has_driver]
+
+
+def scan(force: bool = False) -> ScanResult:
+    """
+    Run a full hardware scan.  Loads from ds_scan.json cache if fresh
+    (< cache_ttl_minutes old) unless force=True.
+    """
+    cfg = get()
+
+    if not force:
+        cached = _load_cache(cfg)
+        if cached:
+            return cached
+
+    events.start("scan", "[scan] Reading machine profile…")
+    with ThreadPoolExecutor(max_workers=2) as ex:
+        profile_f  = ex.submit(get_model_profile)
+        fp_f       = ex.submit(compute_fingerprint)
+        profile    = profile_f.result()
+        machine_id = fp_f.result()
+
+    events.progress("scan", "[scan] Enumerating connected devices…")
+    devices = _enumerate_devices(cfg)
+
+    all_hwids = [h for d in devices for h in d.hwids]
+    installed_versions: dict[str, str] = {}
+    if all_hwids:
+        events.progress("scan", "[scan] Querying installed driver versions…",
+                        total=len(all_hwids))
+        installed_versions = get_installed_versions(all_hwids)
+
+    for dev in devices:
+        ver = next(
+            (installed_versions[h] for h in dev.hwids if h in installed_versions),
+            "",
+        )
+        dev.installed_version = ver
+
+    result = ScanResult(
+        machine_id=machine_id,
+        vendor=profile["vendor"],
+        model=profile["model"],
+        friendly_model=profile.get("friendly_model", ""),
+        serial=profile.get("serial", ""),
+        chassis_type=profile.get("chassis_type", "unknown"),
+        os_build=profile["os_build"],
+        arch=profile.get("arch", "x64"),
+        firmware_version=profile.get("firmware_version", ""),
+        devices=devices,
+        installed_versions=installed_versions,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+    )
+
+    _save_cache(result, cfg)
+    _print_summary(result)
+    return result
+
+
+# ── Cache ──────────────────────────────────────────────────────────────────────
+
+def _cache_path(cfg: dict) -> Path:
+    return Path(cfg.get("cache_dir", "C:\\DriverServer\\client")) / "ds_scan.json"
+
+
+def _load_cache(cfg: dict) -> ScanResult | None:
+    path = _cache_path(cfg)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        ts   = datetime.fromisoformat(data.get("timestamp", "2000-01-01T00:00:00+00:00"))
+        if datetime.now(timezone.utc) - ts > timedelta(minutes=cfg.get("cache_ttl_minutes", 15)):
+            return None
+        # class_name defaults to "" so old caches without it still load correctly
+        devices = [Device(**d) for d in data.pop("devices", [])]
+        return ScanResult(**{**data, "devices": devices})
+    except Exception:
+        return None
+
+
+def _save_cache(result: ScanResult, cfg: dict) -> None:
+    path = _cache_path(cfg)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(result), indent=2))
+    except Exception:
+        pass
+
+
+# ── Device enumeration ─────────────────────────────────────────────────────────
+
+def _enumerate_devices(cfg: dict) -> list[Device]:
+    """
+    Run two pnputil calls in parallel:
+      /ids   → HWIDs + driver_name
+      (none) → class_name per device
+    Merge results by instance_id.
+    """
+    timeout = cfg.get("timeout_short", 30)
+
+    with ThreadPoolExecutor(max_workers=2) as ex:
+        ids_f   = ex.submit(_run_pnputil_ids, timeout)
+        class_f = ex.submit(_run_pnputil_classes, timeout)
+        ids_out   = ids_f.result()
+        class_out = class_f.result()
+
+    if ids_out is None:
+        return []
+
+    devices    = _parse_hwid_output(ids_out)
+    class_map  = _parse_class_output(class_out) if class_out else {}
+
+    for dev in devices:
+        dev.class_name = class_map.get(dev.instance_id, "")
+
+    return devices
+
+
+def _run_pnputil_ids(timeout: int) -> str | None:
+    """pnputil /enum-devices /connected /ids  — HWIDs + driver_name."""
+    try:
+        r = subprocess.run(
+            ["pnputil", "/enum-devices", "/connected", "/ids"],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        return r.stdout
+    except FileNotFoundError:
+        events.error("scan", "[scan] pnputil not found — must run on Windows",
+                     error="pnputil_not_found")
+        return None
+    except Exception as e:
+        events.error("scan", f"[scan] pnputil /ids failed: {e}", error=str(e))
+        return None
+
+
+def _run_pnputil_classes(timeout: int) -> str | None:
+    """pnputil /enum-devices /connected  — class_name per device."""
+    try:
+        r = subprocess.run(
+            ["pnputil", "/enum-devices", "/connected"],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        return r.stdout
+    except Exception:
+        return None
+
+
+# ── pnputil output parsers ─────────────────────────────────────────────────────
+
+def _parse_hwid_output(output: str) -> list[Device]:
+    """Parse /enum-devices /connected /ids output into Device list."""
+    devices:  list[Device] = []
+    current:  dict         = {}
+    in_hwids: bool         = False
+
+    for line in output.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            _flush_device(current, devices)
+            current  = {}
+            in_hwids = False
+        else:
+            in_hwids = _apply_hwid_line(line, stripped, current, in_hwids)
+
+    _flush_device(current, devices)
+    return devices
+
+
+def _apply_hwid_line(line: str, stripped: str, current: dict, in_hwids: bool) -> bool:
+    """Process one non-empty pnputil /ids output line. Returns updated in_hwids flag."""
+    low = stripped.lower()
+    if low.startswith("instance id") and ":" in stripped:
+        current["instance_id"] = stripped.split(":", 1)[1].strip()
+        return False
+    if low.startswith("device description") and ":" in stripped:
+        current["name"] = stripped.split(":", 1)[1].strip()
+        return False
+    if low.startswith("driver name") and ":" in stripped:
+        val = stripped.split(":", 1)[1].strip()
+        if val:
+            current["driver_name"] = val
+        return False
+    if low.startswith(("hardware ids", "compatible ids")):
+        current.setdefault("hwids", [])
+        return True
+    if in_hwids and "\\" in stripped and not stripped.endswith(":"):
+        current.setdefault("hwids", []).append(stripped.upper())
+        return True
+    if ":" in stripped and not line.startswith(" "):
+        return False
+    return in_hwids
+
+
+def _flush_device(current: dict, devices: list[Device]) -> None:
+    if current.get("instance_id"):
+        devices.append(Device(
+            instance_id=current.get("instance_id", ""),
+            device_name=current.get("name", ""),
+            hwids=list(dict.fromkeys(current.get("hwids", []))),
+            has_driver=bool(current.get("driver_name")),
+        ))
+
+
+def _parse_class_output(output: str) -> dict[str, str]:
+    """
+    Parse /enum-devices /connected output into {instance_id: class_name}.
+    Sample lines:
+        Instance ID:  PCI\\VEN_8086...
+        Class Name:   Display adapters
+    """
+    mapping: dict[str, str] = {}
+    current_id               = ""
+
+    for line in output.splitlines():
+        stripped = line.strip()
+        low      = stripped.lower()
+
+        if not stripped:
+            current_id = ""
+            continue
+
+        if low.startswith("instance id") and ":" in stripped:
+            current_id = stripped.split(":", 1)[1].strip()
+        elif low.startswith("class name") and ":" in stripped and current_id:
+            mapping[current_id] = stripped.split(":", 1)[1].strip()
+
+    return mapping
+
+
+# ── Output ─────────────────────────────────────────────────────────────────────
+
+def _print_summary(r: ScanResult) -> None:
+    total = len(r.devices)
+    events.progress("scan", "")
+    events.progress(
+        "scan",
+        f"[scan] {r.vendor} {r.model}  |  {r.chassis_type}  |  OS {r.os_build}",
+        vendor=r.vendor, model=r.model, chassis_type=r.chassis_type,
+        os_build=r.os_build,
+    )
+    events.done(
+        "scan",
+        f"[scan] {total} device(s) — {len(r.has_driver)} with driver, "
+        f"{len(r.missing_driver)} missing",
+        total=total,
+        with_driver=len(r.has_driver), missing=len(r.missing_driver),
+    )
+    if r.missing_driver:
+        events.progress("scan", "[scan] Missing drivers:")
+        for d in r.missing_driver:
+            name  = d.device_name or (d.hwids[0] if d.hwids else d.instance_id)
+            cls   = f"  [{d.class_name}]" if d.class_name else ""
+            events.progress("scan", f"  ✗  {name}{cls}",
+                            device_name=name, class_name=d.class_name)

driverclient-0.2.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: driverclient
+Version: 0.2.0
+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>
+License-Expression: MIT
+Keywords: deployment,driver,pnputil,pxe,windows
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: zstandard>=0.22.0
+Description-Content-Type: text/markdown
+
+# driverclient
+
+Embeddable client for a Driver Server local repo. Scans a Windows machine's
+hardware, resolves and installs drivers from the repo, and captures drivers
+back up to it. Designed to be driven programmatically from a host application
+(for example a PyQt front-end) via a small connector class.
+
+## Install
+
+```bash
+pip install driverclient
+```
+
+## Usage
+
+Create one `DriverClient` per process and call `.run()`:
+
+```python
+from driverclient import DriverClient
+
+client = DriverClient(
+    local_repo_url="http://REPO_HOST:8000",
+    node_key="YOUR_NODE_KEY",
+)
+result = client.run("capture-all")   # or client.run() for the configured default
+```
+
+### Configuration
+
+Config can be supplied three ways and is merged with this priority
+(**highest wins**):
+
+```
+DEFAULTS  <  DS_CLIENT_CONFIG env file  <  config_path file  <  keyword args
+```
+
+- **Args only** — pass keys directly:
+  ```python
+  DriverClient(local_repo_url="http://x:1", node_key="k")
+  ```
+- **File only** — pass a JSON file used as the base:
+  ```python
+  DriverClient(config_path="/etc/driverclient.json")
+  ```
+- **Both** — file as the base, individual keys overridden by kwargs:
+  ```python
+  DriverClient(config_path="/etc/driverclient.json", node_key="override")
+  ```
+
+Passing nothing preserves the default behavior (env file → packaged
+`config.json` → built-in defaults).
+
+A dummy `config.json` ships inside the package as a template. Replace
+`REPLACE_WITH_YOUR_NODE_KEY` and point `local_repo_url` at your repo — or, better,
+supply real values at runtime through the connector.
+
+### Commands
+
+`scan`, `resolve`, `resolve-and-install`, `capture-all`, `capture-missing`,
+`wu-update`, `wu-full`, `automate`.
+
+`client.run()` with no argument uses `DS_CLIENT_COMMAND`, then the
+`default_command` from config.
+
+### Progress events
+
+Every operation reports progress in real time through a structured event stream
+(added in **0.2.0**). Pass an `on_event` callback to `run()` and it is invoked
+synchronously for each step:
+
+```python
+def on_event(ev):        # ev is a driverclient.ClientEvent
+    print(ev.phase, ev.status, ev.message)
+
+client.run("automate", on_event=on_event)
+```
+
+When no callback is given, events fall back to `print` + the
+`driverclient` logger, so the terminal/log experience is unchanged.
+
+Each `ClientEvent` (frozen dataclass, `ev.to_dict()` for transport) has:
+
+| field     | type            | meaning                                             |
+|-----------|-----------------|-----------------------------------------------------|
+| `phase`   | str             | `scan` `resolve` `install` `capture` `windows_update` `dump` `upload` `pipeline` `done` |
+| `status`  | str             | `start` `progress` `ok` `warn` `error` `done`       |
+| `message` | str             | human-readable line (what the fallback prints)      |
+| `current` | int \| None     | counter position (e.g. driver 3 of 12)              |
+| `total`   | int \| None     | counter total                                       |
+| `percent` | float \| None   | 0–100 for long single operations                    |
+| `data`    | dict            | structured specifics (`driver_name`, `hwid`, `path`, `error`, …) |
+| `ts`      | float           | `time.time()` at emit                               |
+
+`phase` and `status` are a fixed, documented vocabulary — this is the interface
+a GUI binds to; treat changes to it as an API change.
+
+> 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.
+
+#### PyQt consumer pattern
+
+Run the (minutes-long, blocking) `client.run(...)` on a **QThread**, never the UI
+thread. The `on_event` callback must **not** touch widgets — it emits a Qt signal
+carrying `event.to_dict()`; a slot on the UI thread updates the widgets. Qt
+delivers cross-thread signals via the receiver's event loop (queued), which is
+the thread-safe way to drive the UI.
+
+```python
+from PyQt6.QtCore import QObject, QThread, pyqtSignal, pyqtSlot
+from driverclient import DriverClient
+
+
+class Worker(QObject):
+    event    = pyqtSignal(dict)     # carries ClientEvent.to_dict()
+    finished = pyqtSignal(object)   # carries the op's result
+
+    def __init__(self, command):
+        super().__init__()
+        self.command = command
+
+    @pyqtSlot()
+    def run(self):
+        client = DriverClient(local_repo_url="http://REPO_HOST:8000",
+                              node_key="YOUR_NODE_KEY")
+        # Called on THIS worker thread — only emit a signal, never touch widgets.
+        result = client.run(self.command, on_event=lambda ev: self.event.emit(ev.to_dict()))
+        self.finished.emit(result)
+
+
+class Panel:
+    """Wire a worker onto a thread and bind its signals to UI-thread slots."""
+    def start(self, command):
+        self.thread = QThread()
+        self.worker = Worker(command)
+        self.worker.moveToThread(self.thread)
+        self.thread.started.connect(self.worker.run)
+        self.worker.event.connect(self.on_event)        # queued → runs on UI thread
+        self.worker.finished.connect(self.on_finished)
+        self.thread.start()
+
+    @pyqtSlot(dict)
+    def on_event(self, ev):
+        # Safe: this runs on the UI thread. Update widgets here.
+        self.status_label.setText(ev["message"])
+        if ev["phase"] == "install" and ev["status"] in ("ok", "error"):
+            self.step_list.addItem(ev["message"])
+        if ev["total"] and ev["current"] is not None:
+            self.progress_bar.setMaximum(ev["total"])
+            self.progress_bar.setValue(ev["current"])
+        elif ev["percent"] is not None:
+            self.progress_bar.setValue(int(ev["percent"]))
+
+    @pyqtSlot(object)
+    def on_finished(self, result):
+        self.thread.quit()
+        self.thread.wait()
+```
+
+## Requirements
+
+- Python >= 3.10
+- Windows target for the actual driver operations (`pnputil`, WMI, DISM).

driverclient-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+driverclient/__init__.py,sha256=yO95efsaJ6BG_w1XM4rI6jFsnLIHmENoCzAPHt9thBE,2854
+driverclient/__main__.py,sha256=hcKwtvsidQC_6fyd9nLE7POmobRXEeZYMTLh1IM9Swg,77
+driverclient/config.json,sha256=-3zVtbU7LxoLgvLNSiYWfwTI3MwxVkmz4vNk4k0Oamc,926
+driverclient/config.py,sha256=lRLxh9sVKtGkGuY53iCUHhljA78jpJuBnqD2qnvUG7g,4289
+driverclient/events.py,sha256=I-01cl-Ojbtxb02ujpAo-VoS4wRHYvawbJWyPfBW5y4,4986
+driverclient/main.py,sha256=qRjF9-GkaWmwVj1O-GU4oFX6SGzXDd8luo2nYPsQB74,2363
+driverclient/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+driverclient/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+driverclient/core/hardware.py,sha256=ut4hRaY88ilDZxJbxiiHqYuhYY3cEisLAaQkWQPapCY,13067
+driverclient/core/http.py,sha256=cqW-pLyvpKvdZ198tYgxkvCcEDRtlQhCTTO6dEHMSJI,10830
+driverclient/ops/__init__.py,sha256=hfZvkgOiNRJkPLu_mlIwxSWhurgxdceHtyDJvNyGLV8,619
+driverclient/ops/automate.py,sha256=Ly8bA-GkxqmzGFZHdT6FiHdqVLi8vGdX3L3tmAoZl7g,5233
+driverclient/ops/capture.py,sha256=1Z8x_Bmf1VmThCf00qqXJV3kIvBUErw_7IVEYw8LJQs,25889
+driverclient/ops/install.py,sha256=AsVprqQHAWtnCLfWWVIzguTcIa65uSOOdrB23BPuovk,10432
+driverclient/ops/resolve.py,sha256=njo94WPt9PV0j2sRuzC1SGbwQ1uW1BLORaaAKFzj3VY,4842
+driverclient/ops/scan.py,sha256=hYkOIEd8CLCL2pjj6wTtwcxJybM-qT5klZDZfayXQT4,10922
+driverclient-0.2.0.dist-info/METADATA,sha256=vXwEUhp8cBxgGAG0nHvhu3z8fXhuD57ZlssmRSzAHxo,6659
+driverclient-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+driverclient-0.2.0.dist-info/RECORD,,

driverclient-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any