driverclient 0.2.0__tar.gz

driverclient-0.2.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+venv/
+.venv/
+*.egg-info/
+
+# Real configs — never commit (contain secrets or real node values)
+backend/config.json
+backend/.env
+frontend/.env
+configs/keys.json
+
+# Secrets fallback
+*.env
+.env
+.env.*
+# Committed safe dev defaults
+!backend/.env.development
+!frontend/.env.development
+# Committed fill-in templates (no real values)
+!configs/templates/**/.env
+!configs/templates/**/config.json
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+
+# Runtime data
+data/
+dist/
+dev_data/
+driverserver-data/
+ds_download/
+ds_capture_temp/
+ds_not_found.json
+ds_wu_tried.json
+ds_cache.json
+
+# Alembic / SQLite local dev databases
+*.db
+*.db-shm
+*.db-wal
+
+# Celery beat schedule file
+celerybeat-schedule
+celerybeat.pid
+
+# IDE — launch.json is developer-specific; add .vscode/settings.json exceptions if needed
+.vscode/launch.json
+.idea/
+*.swp
+
+# Deploy vendor binaries (download separately — see deploy/vendor/README.md)
+deploy/vendor/nssm/
+deploy/vendor/nginx/
+
+# Deploy bundles (generated output)
+deploy/bundles/
+
+# Claude Code
+.claude/

driverclient-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,163 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "driverclient"
+version = "0.2.0"
+description = "Driver Server client with an embeddable connector for config injection at runtime."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Raja Sanaullah", email = "sanaullah@99technologies.com" },
+]
+keywords = ["driver", "windows", "pnputil", "deployment", "pxe"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Operating System :: Microsoft :: Windows",
+    "Intended Audience :: System Administrators",
+]
+dependencies = [
+    "zstandard>=0.22.0",
+]
+
+[project.urls]
+Homepage = "https://example.com/driverclient"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/driverclient"]
+# Ship non-Python package data (config template + type marker) inside the wheel.
+artifacts = [
+    "src/driverclient/config.json",
+    "src/driverclient/py.typed",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/driverclient",
+    "README.md",
+    "pyproject.toml",
+]

driverclient-0.2.0/src/driverclient/__init__.py

@@ -0,0 +1,73 @@
+"""
+driverclient — Driver Server client, packaged for embedding.
+
+Typical use from an embedding app (e.g. a PyQt front-end):
+
+    from driverclient import DriverClient
+
+    # args only
+    client = DriverClient(local_repo_url="http://REPO_HOST:8000", node_key="...")
+
+    # file only
+    client = DriverClient(config_path="/etc/driverclient.json")
+
+    # file as base, individual keys overridden by kwargs
+    client = DriverClient(config_path="/etc/driverclient.json", node_key="...")
+
+    result = client.run("capture-all")   # or client.run() for default_command
+
+Config merge priority (highest wins):
+    DEFAULTS  <  DS_CLIENT_CONFIG env file  <  config_path file  <  kwargs
+"""
+from driverclient import config as _config
+from driverclient.events import ClientEvent, using_sink
+from driverclient.main import run as _run
+
+__all__ = ["DriverClient", "ClientEvent"]
+
+__version__ = "0.2.0"
+
+
+class DriverClient:
+    """
+    Configures the process-global client config, then runs operations.
+
+    A single active client per process is supported: constructing a
+    DriverClient resets and reloads the shared global config singleton.
+    Construct one instance and reuse it; constructing another replaces
+    the active configuration.
+    """
+
+    def __init__(self, config_path: str | None = None, **kwargs) -> None:
+        """
+        Args:
+            config_path: optional path to a JSON config file used as the base.
+                         If omitted, the DS_CLIENT_CONFIG env file or the
+                         packaged config.json is used (existing behavior).
+            **kwargs:    individual config keys that override everything else,
+                         including values from config_path.
+        """
+        _config.reset()
+        self.config = _config.load(path=config_path, overrides=kwargs)
+
+    def run(self, command: str | None = None, on_event=None) -> object:
+        """
+        Run a client operation and return its result object.
+
+        Args:
+            command:  one of the client operations (e.g. "scan", "capture-all",
+                      "automate"). If None, falls back to DS_CLIENT_COMMAND then
+                      the default_command from config.
+            on_event: optional callback ``Callable[[ClientEvent], None]`` invoked
+                      synchronously, in real time, for every progress event the
+                      operation emits. Installed only for the duration of this
+                      run (see events.using_sink) and restored afterwards. When
+                      omitted, events fall back to print + logging so the
+                      terminal experience is unchanged.
+
+        Returns:
+            The operation's result object (ScanResult, InstallResult, ...).
+        """
+        self.on_event = on_event
+        with using_sink(on_event):
+            return _run(command)

driverclient-0.2.0/src/driverclient/__main__.py

@@ -0,0 +1,4 @@
+"""Allow: python -m driverclient"""
+from driverclient.main import run
+
+run()

driverclient-0.2.0/src/driverclient/config.json

@@ -0,0 +1,36 @@
+{
+  "local_repo_url": "http://localhost:8000",
+  "node_key": "REPLACE_WITH_YOUR_NODE_KEY",
+
+  "default_command": "automate",
+
+  "parallel_downloads": 6,
+  "parallel_uploads": 8,
+  "parallel_exports": 4,
+
+  "driver_root": "C:\\DriverServer",
+  "cache_dir":   "C:\\DriverServer\\client",
+  "work_dir":    "C:\\DriverServer\\client\\staging",
+  "cache_ttl_minutes": 15,
+
+  "dump_extensions": [".inf", ".sys", ".cat"],
+  "dump_extensions_overrides": {
+    "system": [".inf", ".sys", ".cat", ".dll"],
+    "usb":    [".inf", ".sys", ".cat", ".dll"]
+  },
+
+  "wu_wait_minutes": 10,
+  "wu_poll_interval_seconds": 30,
+  "wu_ignore_classes": ["hidclass", "bluetooth", "printer"],
+
+  "automate_wu_fallback": true,
+  "automate_re_resolve": false,
+  "force_resolve": false,
+
+  "timeout_tiny":      10,
+  "timeout_short":     30,
+  "timeout_medium":    60,
+  "timeout_long":      120,
+  "timeout_install":   600,
+  "timeout_wmi_slow":  90
+}

driverclient-0.2.0/src/driverclient/config.py

@@ -0,0 +1,98 @@
+"""
+driverclient/config.py — Load client settings.
+
+Merge priority (highest wins):
+  DEFAULTS  <  DS_CLIENT_CONFIG env file  <  file passed to load()  <  overrides
+"""
+import json
+import os
+from pathlib import Path
+
+DEFAULTS: dict = {
+    # ── Server ────────────────────────────────────────────────────────────
+    "local_repo_url":    "http://localhost:8000",
+    "node_key":          "",
+
+    # ── Command ───────────────────────────────────────────────────────────
+    "default_command":   "automate",
+
+    # ── Parallelism ───────────────────────────────────────────────────────
+    "parallel_downloads": 6,
+    "parallel_uploads":   8,
+    "parallel_exports":   4,
+
+    # ── Paths ─────────────────────────────────────────────────────────────
+    "driver_root": "C:\\DriverServer",
+    "cache_dir":   "C:\\DriverServer\\client",
+    "work_dir":    "C:\\DriverServer\\client\\staging",
+
+    # ── Cache TTL ─────────────────────────────────────────────────────────
+    # ds_scan.json / ds_resolve.json are reused if younger than this many minutes
+    "cache_ttl_minutes": 15,
+
+    # ── Capture ───────────────────────────────────────────────────────────
+    # [".inf", ".sys", ".cat"] — minimum for server to redistribute and install
+    # [".inf", ".sys", ".cat", ".dll"] — adds co-installer DLLs
+    # ["*"] — all files in the driver package directory
+    "dump_extensions":   [".inf", ".sys", ".cat"],
+
+    # Per-category extension overrides — key = class_name from pnputil (lowercase)
+    # Categories not listed here use dump_extensions above
+    "dump_extensions_overrides": {
+        "system":  [".inf", ".sys", ".cat", ".dll"],
+        "usb":     [".inf", ".sys", ".cat", ".dll"]
+    },
+
+    # ── Windows Update ────────────────────────────────────────────────────
+    "wu_wait_minutes":          10,
+    "wu_poll_interval_seconds": 30,
+    # Classes to skip when deciding which not-found HWIDs trigger WU.
+    # Empty list = no filtering (default — make no assumptions).
+    # Use lowercase class names as reported by pnputil, e.g. "hidclass", "bluetooth".
+    "wu_ignore_classes":        ["hidclass"],
+
+    # ── Automate flags ────────────────────────────────────────────────────
+    "automate_wu_fallback": True,
+    "automate_re_resolve":  False,
+    "force_resolve":        False,
+
+    # ── HTTP timeouts (seconds) ───────────────────────────────────────────
+    "timeout_tiny":      10,
+    "timeout_short":     30,
+    "timeout_medium":    60,
+    "timeout_long":      120,
+    "timeout_install":   600,
+    "timeout_wmi_slow":  90,
+}
+
+_config: dict | None = None
+
+
+def load(path: str | None = None, overrides: dict | None = None) -> dict:
+    global _config
+    if _config is not None:
+        return _config
+
+    if path:
+        config_path = Path(path)
+    elif "DS_CLIENT_CONFIG" in os.environ:
+        config_path = Path(os.environ["DS_CLIENT_CONFIG"])
+    else:
+        config_path = Path(__file__).parent / "config.json"
+
+    data: dict = {}
+    if config_path.exists():
+        with open(config_path) as fh:
+            data = json.load(fh)
+
+    _config = {**DEFAULTS, **data, **(overrides or {})}
+    return _config
+
+
+def get() -> dict:
+    return load()
+
+
+def reset() -> None:
+    global _config
+    _config = None