PyQt5 Desktop Development
When to Use
Use when building PyQt5 desktop applications — frameless windows, sidebar navigation, panel stacking, background threads, system tray, DPI scaling, single-instance enforcement, or REST API calls from Qt widgets.
Qt Import Order — The Critical Fix
Problem:
ImportError: QtWebEngineWidgets must be imported or Qt.AA_ShareOpenGLContexts must be set before a QCoreApplication instance is created
Fix — correct import order:
import sys
import os
# CRITICAL: Set OpenGL context sharing via QCoreApplication BEFORE QtWidgets import
# QtWidgets import creates QCoreApplication, so the attribute must be set first
from PyQt5.QtCore import Qt, QCoreApplication
QCoreApplication.setAttribute(Qt.AA_ShareOpenGLContexts)
from PyQt5.QtWidgets import *
from PyQt5.QtGui import *
from PyQt5.QtWebEngineWidgets import QWebEngineView # module-level, NOT lazy
Why Qt.AA_ShareOpenGLContexts = True AFTER from PyQt5.QtCore import Qt doesn't work:
The static attribute assignment is too late — from PyQt5.QtCore import Qt itself may trigger module initialization. Use QCoreApplication.setAttribute(Qt.AA_ShareOpenGLContexts) after importing QCoreApplication but BEFORE importing QtWidgets.
Rules:
QCoreApplication.setAttribute(Qt.AA_ShareOpenGLContexts)BEFOREfrom PyQt5.QtWidgets import *(triggersQCoreApplication)QWebEngineViewat module level — lazy imports inside methods cause runtime errors- Order:
sys→os→QtCore (Qt, QCoreApplication)+setAttribute→QtWidgets/QtGui→QtWebEngineWidgets - For headless/offscreen: also set
os.environ['QT_QPA_PLATFORM'] = 'offscreen'andos.environ['QT_OPENGL'] = 'software'before PyQt imports - For software rendering (no GPU): set
os.environ['QT_OPENGL_TYPE'] = 'software'andos.environ['QT_OPENGL'] = 'software'before any Qt imports
Entry point pattern (for modular packages):
# webbuilder_desktop.py — entry point sets Qt attrs BEFORE importing gui
import os
os.environ['QT_OPENGL_TYPE'] = 'software'
os.environ['QT_OPENGL'] = 'software'
from PyQt5.QtCore import QCoreApplication, Qt
QCoreApplication.setAttribute(Qt.AA_ShareOpenGLContexts)
from webbuilder.gui import main # gui imports happen AFTER Qt setup
Headless / Offscreen GUI Testing
import os
os.environ['QT_QPA_PLATFORM'] = 'offscreen'
from PyQt5.QtCore import Qt
Qt.AA_ShareOpenGLContexts = True
from PyQt5.QtWidgets import QApplication
app = QApplication([''])
from desktop_app import WebBuilderApp
window = WebBuilderApp()
print(f'Title: {window.windowTitle()}')
tabs = window.tabs
for i in range(tabs.count()):
print(f'Tab {i}: {tabs.tabText(i)}')
test_gui.py template:
import os
os.environ['QT_QPA_PLATFORM'] = 'offscreen'
os.environ['QT_OPENGL'] = 'software'
from PyQt5.QtCore import Qt, QCoreApplication
QCoreApplication.setAttribute(Qt.AA_ShareOpenGLContexts)
from PyQt5.QtWidgets import QApplication
app = QApplication([''])
from desktop_app import WebBuilderApp
window = WebBuilderApp()
print(f'Title: {window.windowTitle()}')
print(f'Min: {window.minimumSize().width()}x{window.minimumSize().height()}')
tabs = window.tabs
print(f'Tabs: {tabs.count()}')
for i in range(tabs.count()):
t = tabs.widget(i)
print(f' Tab {i} ("{tabs.tabText(i)}"): {type(t).__name__}')
print('=== DONE ===')
Premium QSS Styling
STYLESHEET = """
QMainWindow { background: #0a0a0f; color: #e2e8f0; }
QTabBar::tab {
padding: 14px 24px;
background: transparent;
color: #64748b;
border-bottom: 2px solid transparent;
}
QTabBar::tab:selected {
color: #3b82f6;
border-bottom: 2px solid #3b82f6;
background: rgba(59,130,246,0.08);
}
QToolBar {
background: rgba(30,30,44,0.95);
border-bottom: 1px solid rgba(255,255,255,0.05);
padding: 6px 12px;
spacing: 12px;
}
QPushButton {
background: rgba(255,255,255,0.06);
color: #e2e8f0;
border: 1px solid rgba(255,255,255,0.1);
border-radius: 8px;
padding: 8px 16px;
}
QPushButton:hover { background: rgba(255,255,255,0.12); }
QPushButton[primary="true"] { background: #3b82f6; color: white; border: none; }
QLineEdit, QComboBox {
background: rgba(15,23,42,0.4);
color: #e2e8f0;
border: 1px solid rgba(255,255,255,0.1);
border-radius: 8px;
padding: 8px 12px;
}
QLineEdit:focus { border-color: #3b82f6; }
QWebEngineView { border: none; }
"""
Apply: self.setStyleSheet(STYLESHEET) in __init__.
Single-Instance Enforcement (Windows)
For GUI apps that must never run duplicated, use a Windows named mutex:
import ctypes
from ctypes import wintypes
_SINGLE_INSTANCE_MUTEX = "Global\\YourApp-SingleInstance"
def _acquire_single_instance():
kernel32 = ctypes.windll.kernel32
mutex = kernel32.CreateMutexW(None, False, _SINGLE_INSTANCE_MUTEX)
last_error = kernel32.GetLastError()
if mutex and last_error == 0:
return True # First instance
if mutex:
kernel32.CloseHandle(mutex)
# Another instance running — bring it to foreground
_bring_existing_to_foreground("YourApp Window Title")
return False
def _bring_existing_to_foreground(title_substring: str):
user32 = ctypes.windll.user32
EnumWindowsProc = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
def enum_callback(h, l):
length = user32.GetWindowTextLengthW(h)
if length > 0:
buf = ctypes.create_unicode_buffer(length + 1)
user32.GetWindowTextW(h, buf, length + 1)
if title_substring in buf.value:
user32.ShowWindow(h, 9) # SW_RESTORE
user32.SetForegroundWindow(h)
user32.BringWindowToTop(h)
user32.FlashWindow(h, True)
return False
return True
user32.EnumWindows(EnumWindowsProc(enum_callback), 0)
Call _acquire_single_instance() at the very top of main(), before any Qt imports. If it returns False, sys.exit(0) immediately. This prevents multiple instances from competing for the same QMP/SSH ports.
Stale mutex handling: After taskkill /F, Windows named mutexes persist. When _acquire_single_instance() finds the mutex already exists, it must also check for an actual window (_find_vmharness_window()). If no window exists, the mutex is stale — proceed with a new launch. Keep the mutex handle alive in a global variable so Windows auto-releases it on normal exit. Release it in _cleanup().
Pitfall — file-based lock files are unreliable: Lock files with PID liveness checks can become stale if the process is killed with SIGKILL (PID stays in file). Named mutexes are auto-released by Windows on process death — no stale handle issue. If you must use a file-based lock, use OpenProcess + GetExitCodeProcess with STILL_ACTIVE (259) to detect dead PIDs, and always clean up in atexit.
Pitfall — user demands "only .exe runs": Never create .bat launcher files. The user explicitly rejected them. Use pythonw.exe directly — it's already an executable that suppresses the console window. For distribution, use PyInstaller + NSIS to produce a single App-Installer.exe. The user expects a proper installer executable (App-Installer.exe), NOT a .bat wrapper or a bare PyInstaller output.
Pitfall — PyInstaller hidden imports checklist: When building a PyQt5 app with backend dependencies, ALL of these must be explicitly listed as --hidden-import or the exe will crash silently: PyQt5, aiohttp, qrcode, cryptography, asyncssh, psutil, PIL, pydantic, pydantic_settings, python_dotenv, loguru, matplotlib, docker, kubernetes, mcp, mcp.types, mcp.server. PyInstaller cannot trace dynamic import chains through config modules.
Pitfall — project venv isolation: NEVER use the Hermes venv (C:/Users/Server/AppData/Local/hermes/hermes-agent/venv/) for project code. The user explicitly forbids it. Create a project venv with python -m venv .venv in the project root and install all dependencies there. The project must be fully self-contained.
Pitfall — Docker daemon not running: DockerBackend requires the Docker daemon to be running. In tests, check docker info first and skip if unavailable. The adapter will raise NotConnectedError if connect() hasn't been called. Always wrap backend tests in try/except with skipTest for missing infrastructure.
Pitfall — integration tests reveal async/sync mismatches: When all integration tests fail with RuntimeWarning: coroutine ... was never awaited, the issue is async backends being called synchronously. Run integration tests EARLY (before building the exe) to catch these mismatches. The pattern:
- Write test suite that exercises all backends
- Run tests → identify coroutine warnings
- Create AsyncAdapter to bridge async → sync
- Re-run tests → verify all pass
- Then build exe with adapter included in hidden imports
Pitfall — PyInstaller silently drops hidden imports: When building onefile windowed executables, PyInstaller may fail to trace dynamic import chains (e.g., pydantic_settings imported through vm_mcp.config). The exe exits silently with code 1 and NO stderr — the crash handler works but the missing module prevents startup. Solution: add ALL transitive imports as --hidden-import flags. Always test with --console first to see errors, then switch to --windowed for production.
Pitfall — windowed exes hide all errors: --windowed mode discards stdout/stderr, making debugging impossible. Build a --console debug variant first to diagnose issues, then build the --windowed version. The debug variant will show the actual ModuleNotFoundError that the windowed variant swallows.
Pitfall — uac_admin=True requires elevation: If the PyInstaller spec has uac_admin=True, the exe will fail to launch from non-elevated contexts (WinError 740). Only set uac_admin=True if the app genuinely needs admin rights. For GUI apps that write to Program Files, handle elevation in the NSIS installer instead.
Pitfall — icon generation path mismatch: When generating icons with PIL, ensure OUTPUT_DIR points to the ACTUAL project path. If the project was renamed or moved, the script may write to a stale directory while the real icon files remain unchanged. Always verify the output path matches the current project location.
Pitfall — GitHub URL must match actual remote: The user renamed the repo from QEMU-MCP to VM-Harness. Always verify the actual GitHub URL before writing it into installer scripts, updater scripts, or documentation. The correct URL is https://github.com/LoopyLuci/VM-Harness. An incorrect URL in the installer means updates will fail silently.
Pitfall — icon size in generated icons: When generating icons with PIL, the visual proportion of elements (e.g., monitor screens) must be verified by computing actual pixel dimensions, NOT by relying on vision_analyze which may return cached/stale results. Use python3 -c "size=192; w=int(size*0.75); print(f'{w}/{size}={w/size*100:.0f}%')" to confirm proportions match the user's intent.
Pitfall — async main functions in daemon threads: When running async main() functions (e.g., headless server, streaming bridge) in threading.Thread(daemon=True), wrap them with asyncio.run(). Calling an async function directly without asyncio.run() produces RuntimeWarning: coroutine 'main' was never awaited and the thread exits immediately. Pattern:
def _run_async_service():
import asyncio
while not stop_event.is_set():
try:
from module import main as async_main
asyncio.run(async_main())
except Exception as e:
logger.error("Service error: %s — restarting in 5s", e)
stop_event.wait(5)
Pitfall — async backends called synchronously from GUI: Backend methods (Docker, Kubernetes, QEMU, VMware) are async def but GUI panels call them synchronously. Calling an async method without await returns a coroutine object, not the actual result. Solution: create an AsyncAdapter singleton with a background event loop:
class AsyncAdapter:
_instance = None
def __new__(cls):
if cls._instance is None:
cls._instance = super().__new__(cls)
cls._instance._loop = asyncio.new_event_loop()
cls._instance._thread = threading.Thread(
target=cls._instance._loop.run_forever, daemon=True
)
cls._instance._thread.start()
return cls._instance
def _run_async(self, coro):
future = asyncio.run_coroutine_threadsafe(coro, self._loop)
return future.result(timeout=30)
The adapter converts backend objects (Container, Image, etc.) to dicts for GUI consumption. Always use get_adapter().backend.method() in panels, never call backends directly.
Pitfall — abstract method naming mismatch: Abstract base classes may declare execute_command while implementations use exec_command (or vice versa). This causes TypeError: Can't instantiate abstract class ... with abstract method .... Always grep the abstract method name AND the implementation name before writing tests:
grep -n 'def execute_command\|def exec_command' src/vm_harness/container/backend.py
Rename the abstract method to match the implementation, not the other way around.
Pitfall — StatusIndicator uses set_status(), not set_color(): The StatusIndicator widget in gui/widgets.py has set_status(running: bool, connected: bool = False), not `set_color(QColor). Always check the actual widget API:
# WRONG: self._status_indicator.set_color(QColor("#22c55e"))
# RIGHT: self._status_indicator.set_status(True)
Pitfall — stray n prefix in comments from sed: When using sed to insert lines after import subprocess, the \n escape can produce a literal n prefix on the next line (n# comment instead of # comment). This causes SyntaxError: invalid syntax. Always verify with grep -n '^n#' file.py after batch sed operations.
Pitfall — system tray minimize/restore is just show/hide: Do NOT use setWindowFlags() manipulation for tray minimize/restore — calling setWindowFlags() requires show() to take effect, and the sequence of flag changes causes the window to become unresponsive. The correct pattern is:
- Minimize to tray:
event.ignore()+self.hide() - Restore from tray:
self.showNormal()+self.show()+self.raise_()+self.activateWindow()
Pitfall — CREATE_NO_WINDOW for all subprocess calls: On Windows, every subprocess.Popen() and subprocess.run() creates a console window by default. Add CREATE_NO_WINDOW = 0x08000000 after import subprocess and pass creationflags=CREATE_NO_WINDOW to every call. Without this, CLI windows pop up constantly during VM/container operations.
Pitfall — duplicate method definitions silently shadow: When patching a class multiple times, you can accidentally create duplicate method definitions. The second definition silently shadows the first — no error is raised. Always grep for duplicate method names after patching: grep -n 'def method_name' file.py.
Pitfall — panel key mismatches in _on_signal handlers: When MainWindow.__init__ stores panels with key "guest_terminal" but signal handlers look up "guestterminal", the lookup returns None and data is silently dropped. Always verify panel keys match between storage and lookup: grep -n 'self.panels\[' gui/main_window.py | sort | uniq.
Pitfall — PyInstaller exe exits silently on import error: When a frozen exe exits with code 1 and NO stderr, the cause is a missing module that PyInstaller couldn't trace. The --console debug variant shows the actual ModuleNotFoundError. Build with --console first, diagnose, then switch to --windowed.
Pitfall — backend objects vs dicts: Backend list_vms() may return list[str] (just names) not list[dict]. GUI panels use .get("name") which fails on strings. The adapter must normalize all returns to dicts:
def list_vms(self) -> list:
vms = self._run(self._backend.list_vms())
return [{"name": vm, ...} if isinstance(vm, str) else vm for vm in vms]
Pitfall — VirtualBox backend API differs from QEMU/Docker: The VirtualBox backend (src/vm_harness/hypervisor/virtualbox/backend.py) has these quirks:
list_vms()returnslist[str](VM names), NOTlist[dict]stop_vm(name, force=True)usescontrolvm poweroffwhenforce=True,acpipowerbuttonotherwise- No
power_off()/power_on()methods — usestart_vm()/stop_vm() get_status()returns aVMStatusdataclass withstate.valuefield, not a plain string The adapter must handle these: checkisinstance(result, str)forlist_vms(), andstatus.state.valueforget_status().
Pitfall — QEMU QMP startup hang on headless systems: When start_vm() is called without headless=True, QEMU tries to open a SPICE display. On headless Windows/Linux machines without an X server, this causes QEMU to hang or fail silently, and the QMP monitor never becomes available. Always pass headless=True when starting QEMU on headless systems — this sets -display none and avoids the SPICE/VNC initialization entirely.
Pitfall — package migration requires full consumer sweep: Before moving or deleting a package (e.g., src/vm_mcp/ → src/vm_harness/), grep ALL consumers across the entire codebase:
grep -rn "from vm_mcp\|import vm_mcp" . --include="*.py" | grep -v __pycache__
A package with zero grep results can be deleted safely. A package with 10+ consumers requires gradual migration: move one module → update all imports → run tests → repeat. Deleting a package with active consumers breaks imports silently in PyInstaller-frozen exes (the exe exits with code 1 and no error message).
Pitfall — integration test for VM lifecycle on already-stopped VM: The VirtualBox stop_vm() raises an error if the VM is already stopped. In lifecycle tests, wrap the initial stop in try/except:
try:
backend.stop_vm(name, force=True)
time.sleep(3)
except Exception:
pass # Already stopped
Pitfall — duplicate method definitions in adapters: When patching an adapter class, you can accidentally create duplicate method definitions. The second definition silently shadows the first. For example, get_status() defined twice — the first converts VMStatus objects to strings, the second doesn't. Always grep for duplicate method names after patching:
grep -n "def get_status" gui/async_adapter.py
Pitfall — adapter already bridges async→sync: When using get_adapter().qemu in tests, the adapter methods are already synchronous. Wrapping them in asyncio.run() causes TypeError: a coroutine was expected, got <result>. The adapter's _run() method already calls asyncio.run_coroutine_threadsafe() internally. Never wrap adapter calls in asyncio.run().
Pitfall — Kubernetes create_from_yaml needs a file path: kubernetes.utils.create_from_yaml() expects a file path string, not a StringIO or YAML string. Use tempfile.NamedTemporaryFile for temporary YAML manifests:
import tempfile
with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
f.write(yaml_str)
temp_path = f.name
try:
create_from_yaml(api_client, temp_path)
finally:
os.unlink(temp_path)
Pitfall — Podman CLI differs from Docker CLI: podman create doesn't support --command flag. Pass the command as positional args after the image name:
# WRONG: podman create --name foo alpine:latest --command "sleep 300"
# RIGHT: podman create --name foo alpine:latest /bin/sh -c "sleep 300"
Pitfall — docker exec -it fails on Windows without a TTY: The -t flag allocates a pseudo-TTY, which doesn't exist on Windows without a console. Even -i (interactive without TTY) fails for interactive shells because the shell detects non-TTY and doesn't echo input. For terminal access via WebSocket, use subprocess.run() with capture_output=True for single commands:
# WRONG: subprocess.Popen(["docker", "exec", "-it", name, shell], stdin=PIPE, stdout=PIPE)
# RIGHT: subprocess.run(["docker", "exec", name, "/bin/sh", "-c", cmd], capture_output=True, text=True)
The error message is misleading — docker exec starts successfully but produces no output, making it look like a WebSocket or networking issue. Always test docker exec directly in a terminal before wiring it to a WebSocket handler.
Pitfall — theme attribute naming: In the VM-Harness theme system (gui/theme.py), there is no T.BORDER attribute. Use T.BG_TERTIARY for border colors. Always verify theme attributes exist with grep -n 'BORDER\|BG_' gui/theme.py before referencing them in new panels.
Pitfall — QThread signal timing is flaky in tests: Tests that rely on QThread signal delivery (e.g., worker.progress.connect(...)) can fail intermittently because signal timing is unpredictable in offscreen mode. Add retry logic:
for attempt in range(3):
# ... run test ...
if success:
return
time.sleep(1)
self.fail(f"Test failed after 3 attempts")
A test that passes alone but fails in a full suite is a timing issue, not a logic bug. If a QThread-based test passes individually but fails when run with other tests, increase the timeout or add retry logic rather than debugging the signal connection.
Pitfall — QThread.isRunning() True after finished signal: After a QThread worker emits finished and the event loop exits, isRunning() may still return True because the thread hasn't fully cleaned up. Call worker.wait(timeout_ms) after the event loop exits to ensure complete cleanup before asserting:
loop.exec_()
if worker.isRunning():
worker.wait(5000)
self.assertFalse(worker.isRunning())
Pitfall — hot reloader mtime optimization: When a hot-reloader scans files for changes every second, hashing every .py file is O(n) syscalls/sec. Store (mtime, hash) tuples and only re-hash when stat.st_mtime changes:
def _scan_files(self) -> dict[Path, tuple[float, str]]:
hashes = {}
for path in self._watch_paths:
if path.is_file():
stat = path.stat()
old = self._file_hashes.get(path)
if old is None or old[0] != stat.st_mtime:
hashes[path] = (stat.st_mtime, self._file_hash(path))
else:
hashes[path] = old # Reuse cached hash
return hashes
This drops CPU from O(n) hash/sec to O(1) stat/sec for unchanged files. A project with 200+ .py files saw CPU drop from 12% to <0.5%.
Pitfall — test tautologies hide real bugs: assert True, assert x or True, and # Just verify no crash\nassert True always pass even when the feature is broken. Replace with assertions on actual state:
# WRONG: assert True
# RIGHT: assert panel._usb_table.rowCount() >= 0
# WRONG: assert new_mac != old_mac or True
# RIGHT: assert new_mac != old_mac
Run grep -rn 'assert True\|or True' tests/ to find and fix these before running the suite.
Pitfall — CredentialStore requires store_dir: CredentialManager(store_dir=str(path)) is required. CredentialManager() raises TypeError. For tests, use tempfile.mkdtemp():
from pathlib import Path
import tempfile
_TEST_STORE_DIR = Path(tempfile.mkdtemp(prefix="vmharness_test_"))
store = CredentialManager(store_dir=str(_TEST_STORE_DIR))
Pitfall — can't mock datetime.utcnow: datetime.utcnow is an immutable C type. patch.object(datetime, 'utcnow', ...) raises TypeError: cannot set 'utcnow' attribute of immutable type 'datetime.datetime'. Instead, manipulate metadata directly:
from datetime import datetime, timedelta
meta.expires = datetime.utcnow() - timedelta(hours=2) # Expired 2 hours ago
Pitfall — NSIS installer rebuild after code changes: After rebuilding the PyInstaller exe with new hidden imports or code changes, the NSIS installer must also be rebuilt to bundle the new exe:
# 1. Rebuild exe
.venv/Scripts/python.exe -m PyInstaller --clean --noconfirm --onefile --windowed --name "App" ...
# 2. Rebuild installer
"/c/Program Files (x86)/NSIS/makensis.exe" /V2 installer.nsi
The installer bundles the exe at build time — it does not dynamically reference it.
DPI-Aware Scaling
For multi-monitor and high-DPI setups, scale fonts and icons based on the primary screen's logical DPI:
def _apply_dpi_scaling(self):
from PyQt5.QtWidgets import QApplication
app = QApplication.instance()
if not app:
return
screen = app.primaryScreen()
if not screen:
return
dpi = screen.logicalDotsPerInch()
scale = max(0.8, min(dpi / 96.0, 2.0))
for widget in self.findChildren(QWidget):
font = widget.font()
base_size = font.pointSizeF()
if base_size > 0:
font.setPointSizeF(base_size * scale)
widget.setFont(font)
def resizeEvent(self, event):
super().resizeEvent(event)
self._apply_dpi_scaling()
Call _apply_dpi_scaling() once in __init__() after all widgets are created, and on every resizeEvent. This ensures consistent scaling across 1080p → 4K → ultrawide monitors.
Pitfall — frameless windows cannot be resized by default: Qt.FramelessWindowHint removes the native window frame, which also removes the native resize handles. Add 8 invisible resize grip widgets (20×20px) at all 4 corners and all 4 edge centers with appropriate cursors (SizeFDiagCursor for corners, SizeHorCursor/SizeVerCursor for edges). Implement mousePressEvent/mouseMoveEvent/mouseReleaseEvent on each grip to adjust setGeometry(). Reposition grips on every resizeEvent and call raise_() to keep them above content.
Pitfall — iconSize is a method, not a property: In PyQt5, widget.iconSize is a method (iconSize()), not a property. Use widget.setIconSize(QSize(w, h)) — never assign widget.iconSize = value.
Pitfall — taskbar icon when minimized to tray: When minimizing to system tray, use setWindowFlags(windowFlags | Qt.Tool) to suppress the taskbar entry. On restore, remove the Tool flag and restore Window | CustomizeWindowHint.
Qt Scaling Patterns (Min/Max Ranges)
Use setMinimumSize / setMaximumSize ranges instead of setFixedSize to allow fluid rescaling:
| Instead of | Use |
|---|---|
setFixedWidth(180) |
setMinimumWidth(160) + setMaximumWidth(280) |
setFixedHeight(40) |
setMinimumHeight(36) |
setFixedSize(36, 24) |
setMinimumSize(36, 24) + setMaximumSize(48, 32) |
This lets the sidebar expand on wide screens and contract on narrow ones without clipping content. Also add setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Preferred) to sidebar buttons so they stretch with the sidebar width.
REST API Calls from Qt Widgets
When a Qt panel needs to trigger backend operations, use urllib.request with a short timeout (Qt main thread blocks on network I/O — always use short timeouts):
def _on_start_vm(self):
import urllib.request
import json as _json
try:
req = urllib.request.Request(
"http://127.0.0.1:8443/api/v1/vms/test/start",
method="POST",
)
with urllib.request.urlopen(req, timeout=10) as resp:
data = _json.loads(resp.read())
self.add_activity(f"VM start: {data.get('detail', 'ok')}")
except Exception as e:
self.add_activity(f"VM start failed: {e}")
Never call qmp_bridge.cont() for VM start — that only resumes a paused VM, it doesn't start a stopped one. Always use the REST API for lifecycle operations.
Common Pitfalls
- Import order — Qt attribute must be set before any PyQt import
- QWebEngineView lazy import — Causes runtime errors
addAction(text, None, shortcut)— PyQt5 doesn't acceptNone; use real method- Offscreen on Windows — Set
QT_QPA_PLATFORM=offscreenbefore PyQt imports - Large file writes —
write_filemay truncate; verify file size after - Qt + MCP clicking — Background clicks via
computer_usedo NOT reliably reach Qt widgets. Verify logic via integration tests, use MCP capture for visual verification only. Elevated to workflow-level constraint: When building Qt apps, assume MCP clicks will NOT work on Qt widgets. Design your testing strategy around: (a) integration tests for logic, (b) headless offscreen for widget creation, (c) MCP capture for visual verification only. Do NOT rely on MCP clicking for GUI workflow testing. - Module reorganization — When moving modules to
contrib/, update ALL import paths. Usesearch_filesto find allfrom webbuilder.Xreferences and update tofrom webbuilder.contrib.X. Common pattern:from webbuilder.feedback import X→from webbuilder.contrib.feedback import X. setStretchFactorrequires int, not float —layout.setStretchFactor(widget, 0.5)raisesTypeErroror silently mis-ratios the layout. Use integer stretch values only (e.g.setStretchFactor(widget, 1)).QTextBrowserforappendHtml—QTextEdit.appendHtml()works butQTextBrowseris the read-only equivalent and is preferred for log viewers/display panels where the user only reads content. UseQTextBrowserwhen the widget is purely display-only;QTextEditwhen the user can also edit.- matplotlib backend:
backend_qtagg, notbackend_qt— matplotlib ≥ 3.8 renamed the Qt backend.from matplotlib.backends.backend_qt import FigureCanvasQTAggdoes NOT exist in matplotlib 3.11. Usefrom matplotlib.backends.backend_qtagg import FigureCanvasQtAgginstead. The class name changed fromFigureCanvasQTAggtoFigureCanvasQtAgg. Import via__import__("matplotlib.backends.backend_qtagg", fromlist=["FigureCanvasQtAgg"]).FigureCanvasQtAggto avoid import errors if the backend is missing. - Clean shutdown with signal handlers — for PyQt5 apps with background asyncio bridges (SSH, QMP, HTTP), always install signal handlers and wrap the main event loop:
Without this, background threads leak on exit and SSH connections remain open.import signal def signal_handler(signum, frame): app._cleanup() # Stop bridges, disconnect SSH sys.exit(0) signal.signal(signal.SIGINT, signal_handler) signal.signal(signal.SIGTERM, signal_handler) try: exit_code = app.exec_() except KeyboardInterrupt: app._cleanup() exit_code = 0 except Exception as e: logger.error("GUI crashed: %s", e) app._cleanup() exit_code = 1 sys.exit(exit_code) - QThread + asyncio bridge — for panels that call async functions (SSH, QMP, HTTP),
see threading-asyncio-bridge.md. Prefer
threading.ThreadoverQThreadfor asyncio bridges — simpler and more reliable on Windows. - Check whether async APIs are class methods or module-level functions — before writing
Client().connect(), verify the actual API. Many async SSH/QMP libraries expose module-level functions (ssh_client.connect()) or a class PLUS module-level helpers (QMPClientclass +query_status(client)helper). Bridges must match the actual API. - Stability + Performance systems: WebBuilder uses 12-component stability system (StabilityMonitor, AutoSaveManager, InputValidator, OperationTimeout, RetryManager, CircuitBreaker, HealthChecker, ResourceGuard, StateManager, ErrorBoundary, MemoryGuard, ThreadSafety) and 14-component performance system (LazyLoader, CacheManager, AsyncExecutor, BatchProcessor, MemoryPool, Debouncer, Throttler, ParallelExecutor, PerformanceProfiler, ConnectionPool, LazyInit, ResourcePool, CompressionManager, IncrementalUpdater) for robustness.
- Async-to-sync adapter pattern: When GUI panels need to call async backend methods, never call them directly. Create an
AsyncAdaptersingleton with a background event loop that usesasyncio.run_coroutine_threadsafe()to execute coroutines and return results synchronously. The adapter also normalizes backend objects (dataclasses, custom types) to plain dicts for GUI consumption. Include the adapter module in PyInstaller hidden imports.
12. Hardware Abstraction Layer (Multi-Threading + Multi-GPU)
For CPU/GPU-aware work distribution, implement a Hardware Abstraction Layer.
Modules:
webbuilder/hardware/
├── detector.py # CPU/GPU/memory detection (NVML, psutil, platform)
├── gpu.py # GPUManager — device assignment, load tracking
├── scheduler.py # TaskScheduler — distribute work across threads + GPUs
├── pool.py # ComputePool — dynamic worker scaling
└── workstealing.py # WorkStealingQueue — optimal load balancing
Detection priority:
- NVIDIA:
pynvml(NVML) → fallback tonvidia-smisubprocess - AMD:
rocm-smisubprocess - Intel: platform-specific detection
- Apple Silicon:
platform.system() == 'Darwin' and platform.machine() == 'arm64'
Task Scheduler pattern:
from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
class TaskScheduler:
def __init__(self):
info = get_hardware_info()
self._thread_pool = ThreadPoolExecutor(max_workers=info.cpu.optimal_thread_count)
self._process_pool = ProcessPoolExecutor(max_workers=max(1, info.cpu.cores_physical - 1))
def submit(self, callback, use_gpu=False, **kwargs):
if use_gpu and gpu_manager.has_gpu:
return self._thread_pool.submit(self._execute_gpu_task, ...)
return self._thread_pool.submit(self._execute_cpu_task, ...)
}
Work-stealing queue pattern:
- Each worker has a local deque
- Idle workers steal from the end of busy workers' queues
- Priority queue for global overflow
- Auto-scales workers based on queue depth
Pitfall: Process pools cannot reference module-level singletons (they get pickled/copied). Pass data explicitly.
13. MCP (Model Context Protocol)
For AI-to-application tool integration, implement an MCP server.
Pattern:
# JSON-RPC 2.0 envelope
class MCPRequest:
jsonrpc: str = "2.0"
id: Optional[str]
method: str # "initialize", "tools/list", "tools/call"
params: dict
class MCPResponse:
result: Any = None
error: Optional[dict] = None
Server must implement:
initialize→ return protocol version + server infotools/list→ return tools withname,description,inputSchematools/call→ execute tool by name with arguments
Typical tools for a web builder:
create_section,edit_section,delete_sectionlist_sections,get_project_info,export_projectset_theme,create_project,save_project,load_projectadd_snippet,get_dom_tree,undo,redo
Client connects to external MCP servers via stdio (subprocess) or SSE.
GUI Integration:
class MCPSettingsDialog(QDialog):
# Tab 1: Server list (add/edit/remove/connect/disconnect)
# Tab 2: Available tools from connected servers
# Tab 3: About MCP
Pitfall: MCP server runs IN-PROCESS with the GUI (not a separate process). Tool handlers receive self.window to interact with the application. This means a crashing tool handler crashes the app — wrap handlers in try/except.
See mcp-integration.md for implementation details.
14. Live AI Model Discovery (NO Hardcoded Models)
Critical user requirement: Models MUST NOT be hardcoded. They must be fetched live from provider APIs.
Providers to support:
- OpenAI (
/v1/models) - Anthropic (
/v1/models) - OpenRouter (
/api/v1/models?limit=500) — 400+ models - xAI Grok (
/v1/models) - Nous Research (
/v1/models) - Ollama (
/api/tags— local, no key needed) - LM Studio (
/v1/models— local, no key needed)
Architecture:
# webbuilder/ai/__init__.py
class BaseProvider(ABC):
api_key: str
_models_cache: list[ModelInfo]
_cache_ttl = timedelta(minutes=30)
@abstractmethod
async def fetch_models(self) -> list[ModelInfo]: ...
@abstractmethod
async def stream_chat(self, messages, model, **kwargs) -> AsyncIterator[str]: ...
class OpenAIProvider(BaseProvider):
base_url = "https://api.openai.com/v1"
# GET /v1/models → parse data[].id
class AnthropicProvider(BaseProvider):
base_url = "https://api.anthropic.com/v1"
# GET /v1/models → parse data[].id, display_name
class OpenRouterProvider(BaseProvider):
base_url = "https://openrouter.ai/api/v1"
# GET /api/v1/models?limit=500 → parse data[].id, name, pricing
class GrokProvider(BaseProvider):
base_url = "https://api.x.ai/v1"
# GET /v1/models → parse data[].id
class NousProvider(BaseProvider):
base_url = "https://inference-api.nousresearch.com/v1"
# GET /v1/models → parse data[].id
class OllamaProvider(BaseProvider):
base_url = "http://localhost:11434"
# GET /api/tags → parse models[].name
class LMStudioProvider(BaseProvider):
base_url = "http://localhost:1234/v1"
# GET /v1/models → parse data[].id
Model Router:
class ModelRouter:
providers: dict[str, BaseProvider]
fallback_order: list[str]
async def get_all_models(self) -> list[ModelInfo]:
# Fetch from all providers, aggregate results
async def stream_chat(self, messages, model, provider_id=None):
# If provider specified, use it
# Otherwise try each provider in fallback order
GUI Integration:
class FetchModelsThread(QThread):
models_loaded = pyqtSignal(list)
error_occurred = pyqtSignal(str)
def run(self):
# Setup providers from environment variables
config = {
"openai_api_key": os.environ.get("OPENAI_API_KEY", ""),
"anthropic_api_key": os.environ.get("ANTHROPIC_API_KEY", ""),
"openrouter_api_key": os.environ.get("OPENROUTER_API_KEY", ""),
"xai_api_key": os.environ.get("XAI_API_KEY", ""),
"nous_api_key": os.environ.get("NOUS_API_KEY", ""),
}
router = setup_providers(config)
models = await router.get_all_models()
self.models_loaded.emit(models)
Pattern:
- Set environment variables for API keys
- Call
setup_providers(config)to initialize providers - Call
await router.get_all_models()to fetch all models live - Display in dropdown grouped by provider, free models first
- Use
FetchModelsThreadfor non-blocking GUI updates
See live-model-discovery.md for implementation details.
When building features rapidly, method signatures evolve. Tests written for idealized interfaces often mismatch actual implementations.
The pattern:
- Build feature with working implementation
- Write tests based on idealized API design
- Discover mismatches during test runs
- Inspect actual signatures:
inspect.signature(Class.method) - Fix tests to match actual APIs (or refactor implementation)
Common mismatches:
- Method name:
get_exporter()→export() - Parameter count:
export(project, format, path)→export(project, path) - Parameter name:
form_id→form - Return type:
dict→dict[str, Any] - Dataclass field:
type→event_type
Key insight: 80%+ test pass rate is healthy. Chasing 100% often means rewriting working code to match test expectations, or vice versa. Pick the direction that produces the cleanest API.
Inspection workflow:
import inspect
from webbuilder.module import ClassName
print(inspect.signature(ClassNam
…(truncated)