PySide6 QML Bridge Layer
The bridge layer is the critical interface between Python business logic and QML views. Bridge classes are QObject subclasses that expose properties, signals, and slots to QML via Qt's meta-object system.
Bridge Architecture
┌──────────────────────────────────────────────┐ │ QML View │ │ Text { text: jobBridge.jobNumber } │ │ Button { onClicked: jobBridge.activateJob() }│ └───────────────┬──────────────────────────────┘ │ Property bindings, signal connections ┌───────────────▼──────────────────────────────┐ │ Bridge (QObject) │ │ @Property, @Slot, Signal │ │ Delegates to Controller │ └───────────────┬──────────────────────────────┘ │ ┌───────────────▼──────────────────────────────┐ │ Controller │ │ Business logic, model updates │ └──────────────────────────────────────────────┘
Bridge Class Pattern
"""views/bridge.py — QObject bridge classes exposed to QML.""" from PySide6.QtCore import QObject, Property, Signal, Slot, QStringListModel from PySide6.QtQml import QmlElement
from my_app.controllers.job_controller import JobController from my_app.utils.signals import SignalRegistry
class JobBridge(QObject): """ Bridge between QML views and the JobController.
Exposes job data as Qt properties with NOTIFY signals
and controller actions as invokable slots.
"""
# --- NOTIFY Signals (one per property group) ---
job_number_changed = Signal()
job_name_changed = Signal()
is_busy_changed = Signal()
jobs_list_changed = Signal()
error_changed = Signal()
def __init__(
self,
controller: JobController,
signals: SignalRegistry,
parent: QObject | None = None,
) -> None:
super().__init__(parent)
self._controller = controller
self._signals = signals
# Internal state (backing fields for properties)
self._job_number: str = ""
self._job_name: str = ""
self._is_busy: bool = False
self._jobs_list: list[str] = []
self._error_message: str = ""
# Connect to application signals
self._signals.job_changed.connect(self._on_job_changed)
# -----------------------------------------------------------------
# Qt Properties (exposed to QML via Property decorator)
# -----------------------------------------------------------------
@Property(str, notify=job_number_changed)
def jobNumber(self) -> str:
return self._job_number
@Property(str, notify=job_name_changed)
def jobName(self) -> str:
return self._job_name
@Property(bool, notify=is_busy_changed)
def isBusy(self) -> bool:
return self._is_busy
@Property(list, notify=jobs_list_changed)
def jobsList(self) -> list:
return self._jobs_list
@Property(str, notify=error_changed)
def errorMessage(self) -> str:
return self._error_message
# -----------------------------------------------------------------
# Slots (callable from QML)
# -----------------------------------------------------------------
@Slot(str)
def activateJob(self, job_id: str) -> None:
"""Activate a job — delegates to controller."""
self._set_busy(True)
success = self._controller.activate_job(job_id)
if not success:
self._set_error("Failed to activate job")
self._set_busy(False)
@Slot(str, result=bool)
def createJob(self, job_number: str) -> bool:
"""Create a new job — returns success."""
return self._controller.create_job(job_number)
@Slot()
def refreshJobs(self) -> None:
"""Reload the jobs list from repository."""
jobs = self._controller.get_all_jobs()
self._jobs_list = [j.job_number for j in jobs]
self.jobs_list_changed.emit()
@Slot(str)
def openJobFolder(self, job_id: str) -> None:
"""Open job folder in file explorer."""
self._controller.open_job_folder(job_id)
# -----------------------------------------------------------------
# Internal signal handlers
# -----------------------------------------------------------------
def _on_job_changed(self, job_id: str) -> None:
"""Handle global job_changed signal."""
job = self._controller.get_job(job_id)
if job:
self._job_number = job.job_number
self._job_name = job.job_name or ""
self.job_number_changed.emit()
self.job_name_changed.emit()
# -----------------------------------------------------------------
# Private helpers
# -----------------------------------------------------------------
def _set_busy(self, busy: bool) -> None:
if self._is_busy != busy:
self._is_busy = busy
self.is_busy_changed.emit()
def _set_error(self, message: str) -> None:
self._error_message = message
self.error_changed.emit()
Registering Bridges with QML
Option A: Context Properties (recommended for singletons)
In app.py — _register_qml_types()
def _register_qml_types(self) -> None: ctx = self._engine.rootContext()
self._job_bridge = JobBridge(
controller=self._controllers["job"],
signals=self._signals,
)
ctx.setContextProperty("jobBridge", self._job_bridge)
self._settings_bridge = SettingsBridge(
controller=self._controllers["settings"],
signals=self._signals,
)
ctx.setContextProperty("settingsBridge", self._settings_bridge)
Usage in QML:
Text { text: jobBridge.jobNumber } Button { onClicked: jobBridge.activateJob("1234567") }
Option B: QML Type Registration (for instantiable types)
from PySide6.QtQml import qmlRegisterType
Register before engine.load()
qmlRegisterType(JobBridge, "MyApp", 1, 0, "JobBridge")
Usage in QML:
import MyApp 1.0
JobBridge { id: jobBridge // properties auto-bound }
Option C: QmlElement Decorator (PySide6 6.5+)
from PySide6.QtQml import QmlElement
QML_IMPORT_NAME = "MyApp" QML_IMPORT_MAJOR_VERSION = 1 QML_IMPORT_MINOR_VERSION = 0
@QmlElement class JobBridge(QObject): ...
Property Type Mapping
Python Type Qt/QML Type Property Decorator Notes
str
string
Property(str, ...)
Most common
int
int
Property(int, ...)
float
real / double
Property(float, ...)
bool
bool
Property(bool, ...)
list
var (JS array) Property(list, ...)
Copies to JS array
dict
var (JS object) Property('QVariant', ...)
Use QVariant type hint
QUrl
url
Property(QUrl, ...)
For file/resource paths
QColor
color
Property(QColor, ...)
QStringList
list<string>
Property('QStringList', ...)
Preferred for string lists
QVariantList
var
Property('QVariantList', ...)
For mixed-type lists
QVariantMap
var
Property('QVariantMap', ...)
For key-value objects
Exposing List Models to QML
For table/list views, use QAbstractListModel :
from PySide6.QtCore import QAbstractListModel, Qt, QModelIndex
class JobListModel(QAbstractListModel): """Exposes a list of jobs for QML ListView/Repeater."""
# Custom roles
JobNumberRole = Qt.UserRole + 1
JobNameRole = Qt.UserRole + 2
StatusRole = Qt.UserRole + 3
def __init__(self, parent=None):
super().__init__(parent)
self._jobs: list[dict] = []
def roleNames(self):
return {
self.JobNumberRole: b"jobNumber",
self.JobNameRole: b"jobName",
self.StatusRole: b"status",
}
def rowCount(self, parent=QModelIndex()):
return len(self._jobs)
def data(self, index, role=Qt.DisplayRole):
if not index.isValid() or index.row() >= len(self._jobs):
return None
job = self._jobs[index.row()]
if role == self.JobNumberRole:
return job.get("job_number", "")
if role == self.JobNameRole:
return job.get("job_name", "")
if role == self.StatusRole:
return job.get("status", "")
return None
def update_jobs(self, jobs: list[dict]) -> None:
"""Replace the jobs list and notify QML."""
self.beginResetModel()
self._jobs = jobs
self.endResetModel()
Register as context property:
ctx.setContextProperty("jobListModel", self._job_list_model)
Use in QML:
ListView { model: jobListModel delegate: Row { Text { text: jobNumber } Text { text: jobName } Text { text: status } } }
Naming Conventions
Context Convention Example
Python class names PascalCase JobBridge
Python backing fields _snake_case
self._job_number
Qt Property names camelCase jobNumber
Signal names snake_case (Python) job_number_changed
Slot names camelCase (QML-facing) activateJob
QML context property camelCase jobBridge
Common Anti-Patterns
Never embed business logic in the bridge
❌ WRONG — bridge doing controller work
@Slot(str) def activateJob(self, job_id: str) -> None: job = self._repository.get_job(job_id) # NO direct DB access self._ini_service.write(job) # NO service calls self._broker.publish("job.activated") # NO broker calls
✅ CORRECT — bridge delegates to controller
@Slot(str) def activateJob(self, job_id: str) -> None: self._controller.activate_job(job_id)
Never manipulate QML from Python
❌ WRONG — reaching into QML from Python
root = self._engine.rootObjects()[0] label = root.findChild(QObject, "statusLabel") label.setProperty("text", "Active")
✅ CORRECT — update a property, QML binding does the rest
self._status_text = "Active" self.status_text_changed.emit()
Always emit NOTIFY signals
❌ WRONG — property changes without notification
self._job_number = "1234567"
✅ CORRECT — emit so QML bindings update
self._job_number = "1234567" self.job_number_changed.emit()
Thread Safety
For long-running operations, use QThread or Python threads with signal marshalling:
from PySide6.QtCore import QThread, Signal
class WorkerThread(QThread): finished = Signal(object) # result error = Signal(str) # error message
def __init__(self, task_fn, parent=None):
super().__init__(parent)
self._task_fn = task_fn
def run(self):
try:
result = self._task_fn()
self.finished.emit(result)
except Exception as e:
self.error.emit(str(e))
In bridge:
@Slot() def loadJobsAsync(self) -> None: self._set_busy(True) worker = WorkerThread(self._controller.get_all_jobs, self) worker.finished.connect(self._on_jobs_loaded) worker.error.connect(self._on_load_error) worker.start()
def _on_jobs_loaded(self, jobs) -> None: self._jobs_list = [j.job_number for j in jobs] self.jobs_list_changed.emit() self._set_busy(False)
References
-
PySide6 QML Integration Tutorial
-
PySide6 Property System
-
QAbstractListModel in PySide6