Skip to main content

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

pip install driverclient

Usage

Create one DriverClient per process and call .run():

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:
    DriverClient(local_repo_url="http://x:1", node_key="k")
    
  • File only — pass a JSON file used as the base:
    DriverClient(config_path="/etc/driverclient.json")
    
  • Both — file as the base, individual keys overridden by kwargs:
    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:

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.

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:

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.

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.

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).

Metadata

Release files for driverclient 0.2.31

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for driverclient 0.2.31
File Size Uploaded Provenance Actions
driverclient-0.2.31.tar.gz 53.4 kB Without provenance Details for driverclient-0.2.31.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for driverclient 0.2.31
File Interpreter ABI Platform Actions
driverclient-0.2.31-py3-none-any.whl Python 3 none any Details for driverclient-0.2.31-py3-none-any.whl

Total release size: 115.5 kB

Release files / driverclient-0.2.31.tar.gz

Download URL driverclient-0.2.31.tar.gz
Size 53.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b30c900fb197badf0cd3243159cf026d72db9b240b427bea068066860742b3fa
BLAKE2b-256 checksum
How to use checksums
77af72f6cf3578e3eb236bede65f2921b07467bd44613f1fa561b4aa5bc975be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Release files / driverclient-0.2.31-py3-none-any.whl

Download URL driverclient-0.2.31-py3-none-any.whl
Size 62.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9aaec4204c85ce7508963c319868cd93e088e5a3fec41d2592bc62d97dfa94f4
BLAKE2b-256 checksum
How to use checksums
6a58e49d77bdf843eb8799ceed1c58974f7d8b739ec151d8470000c21db9e637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Security for driverclient 0.2.31

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.31 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page