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
installevent carriesdata["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).
Building & releasing
The version lives in pyproject.toml and src/driverclient/__init__.py (kept
in lockstep by bump_version.py). System Assistant consumes this as a pip package
(driverclient>=X in its requirements.txt), so a code change ships by publishing
a new version — PyPI never overwrites an existing one.
With uv (no extra tooling to install)
uv build runs the hatchling backend in an isolated env; uvx runs twine
ephemerally — neither needs a pre-installed build/twine.
cd client-package
uv build # → dist/driverclient-<version>-py3-none-any.whl (+ .tar.gz)
uvx twine upload dist/* # publish (uses ~/.pypirc)
Bump vs. no-bump — pick the right one
- Version NOT set yet → bump then build:
make release VERSION_PART=patch|minor|major(bump → build → smoke, no upload), thentwine upload dist/*(oruvx twine upload dist/*). - Version already set to the exact target (e.g. someone set it by hand): build
without bumping —
uv build(ormake clean && make build), then upload. Do not runmake release/bump_version.pyhere — it would bump past the intended version.
Full flow (TestPyPI dry-run, .pypirc token, post-publish verify): see
RELEASING.md.
Metadata
Release files for driverclient 0.2.42
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| driverclient-0.2.42.tar.gz | 58.2 kB | Without provenance | Details for driverclient-0.2.42.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| driverclient-0.2.42-py3-none-any.whl | Python 3 | none | any | Details for driverclient-0.2.42-py3-none-any.whl |
Total release size: 124.9 kB
Release files / driverclient-0.2.42.tar.gz
| Download URL | driverclient-0.2.42.tar.gz |
|---|---|
| Size | 58.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0599688313f5a2c012f35726b6db537de6d6b40b92efb37fb0487682245494b1
|
|
BLAKE2b-256 checksum How to use checksums |
1cd323e5cbe820853da7f9d8ebdccbb51417a3f63842ea9798a2f73c8e9fda3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / driverclient-0.2.42-py3-none-any.whl
| Download URL | driverclient-0.2.42-py3-none-any.whl |
|---|---|
| Size | 66.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1c782f5e751af86d8b0b421ccda5fec19c1991f3654dc7a608efcfc08f4e3b82
|
|
BLAKE2b-256 checksum How to use checksums |
b285a1c4d6ffdf344187af30b36e503758db6b902aeaf692bfd881eb475438b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for driverclient 0.2.42
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.