Working with Qt

Overview

Qt apps use PySide6 with qasync for async integration. Architecture follows Manager -> Service -> Wrapper layering. Never block the event loop.

Key Rules

1. PySide6 (LGPL, no system deps) over PyQt
2. Never block event loop: no subprocess.run(), no time.sleep(), no sync HTTP
3. qasync bridges asyncio and Qt event loops
4. ThreadPoolExecutor wraps blocking third-party APIs
5. Typed wrappers around untyped libraries, enforced via ruff banned-api
6. Signals at class level, not in __init__
7. camelCase for Qt event handlers (ignore ruff N802), snake_case for our slots

Architecture