Reactive Properties Tutorial

In this tutorial you will learn how to make a QObject reactive and QML-bindable with very little code, using the decorators from the PySide6.QtQmlFeatures module: auto_properties(), computed(), watch(), and effect().

We start from a small shopping-cart class written the traditional way, with Property and Signal, and then rewrite it step by step, letting each decorator remove a chunk of boilerplate.

Note

The PySide6.QtQmlFeatures module is currently in technical preview.

The example

The cart has two inputs and one derived value:

• price and quantity: plain integer inputs.

• total: always equal to price * quantity.

On top of that we want two reactions whenever something changes:

• warn when the price jumps by more than 50% (we need the old and new values to decide), and

• log the cart’s state after any change (we only need the new state).

These three needs map exactly onto the three decorators, as you will see: total becomes a computed(), the price jump warning becomes a watch(), and the logging becomes an effect().

Step 1: The traditional approach

Without the new decorators, every property is declared with the Property decorator and needs a backing attribute, a getter, a setter, and a notify Signal. The derived total has to be recomputed by hand, and the two reactions have to be called explicitly from inside each setter.

from PySide6.QtCore import QObject, Property, Signal


class Cart(QObject):
    # One notify signal per property, declared by hand.
    priceChanged = Signal()
    quantityChanged = Signal()
    totalChanged = Signal()

    def __init__(self, parent=None):
        super().__init__(parent)
        self._price = 10
        self._quantity = 2
        self._total = self._price * self._quantity

        # Keep the derived value in sync by hand
        # whenever an input changes, recompute the total.
        self.priceChanged.connect(self._recompute_total)
        self.quantityChanged.connect(self._recompute_total)

    # price: backing field + getter + setter, declared with @Property.
    @Property(int, notify=priceChanged)
    def price(self):
        return self._price

    @price.setter
    def price(self, value):
        if self._price == value:
            return
        old = self._price
        self._price = value
        self.priceChanged.emit()
        # "watch" behaviour: react to the old and new values by hand.
        if value > old * 1.5:
            print(f"warning: price jumped {old} -> {value}")
        # "effect" behaviour: log the new state by hand.
        self._log_state()

    # quantity: the same boilerplate, a second time.
    @Property(int, notify=quantityChanged)
    def quantity(self):
        return self._quantity

    @quantity.setter
    def quantity(self, value):
        if self._quantity == value:
            return
        self._quantity = value
        self.quantityChanged.emit()
        self._log_state()

    # total: read-only derived property, kept in sync manually. With no
    # setter it cannot be written from QML.
    @Property(int, notify=totalChanged)
    def total(self):
        return self._total

    def _recompute_total(self):
        new_total = self._price * self._quantity
        if new_total != self._total:
            self._total = new_total
            self.totalChanged.emit()

    def _log_state(self):
        print(f"cart: {self._price} x {self._quantity}")


if __name__ == "__main__":
    cart = Cart()
    print(f"initial total: {cart.total}")
    cart.price = 16      # 16 > 10 * 1.5, so the jump warning fires
    cart.quantity = 3
    print(f"final total: {cart.total}")

This works, but notice everything you had to write by hand:

• three Signal declarations,

• a backing field, a getter, and a setter for price and quantity,

• a read-only total property plus a _recompute_total slot connected to both inputs,

• the old/new comparison for the price jump warning, inlined in the setter, and

• a _log_state call inlined in every setter.

The rest of the tutorial removes these one group at a time.

Step 2: Generate properties with @auto_properties and @computed

auto_properties() is a class decorator. It turns every plain self.<name> = <value> assignment in __init__ into a real Q_PROPERTY with a <name>Changed notify signal, and it turns every computed() method into a cached, read-only property.

from PySide6.QtCore import QObject
from PySide6.QtQmlFeatures import auto_properties, computed


# @auto_properties turns the plain "self.price = ..." / "self.quantity = ..."
# assignments into real Q_PROPERTYs with priceChanged/quantityChanged notify
# signals, and turns the @computed method into a cached, read-only property.
@auto_properties
class Cart(QObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.price = 10
        self.quantity = 2

    # 'total' recomputes only when price or quantity changes. No backing
    # field, no notify signal, no manual recompute wiring.
    @computed("price", "quantity")
    def total(self) -> int:
        return self.price * self.quantity


if __name__ == "__main__":
    cart = Cart()
    print(f"initial total: {cart.total}")
    cart.price = 16
    cart.quantity = 3
    print(f"final total: {cart.total}")

The @computed("price", "quantity") decorator declares that total depends on price and quantity. The value is cached and recomputed only when one of those dependencies changes; its totalChanged signal is emitted automatically, so any QML binding reading total refreshes on its own. The return annotation (-> int) lets @auto_properties infer the Qt type of the property.

Compared to Step 1, the backing fields, getters, setters, the three explicit Signal objects, and the entire _recompute_total wiring are gone.

Step 3: React to changes with @watch

A watch() method observes a single property. After that property changes, the method is called with a Change describing what happened: it carries the property name, the old value, the new value, and the owner.

from PySide6.QtCore import QObject
from PySide6.QtQmlFeatures import auto_properties, computed, watch, Change


@auto_properties
class Cart(QObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.price = 10
        self.quantity = 2

    @computed("price", "quantity")
    def total(self) -> int:
        return self.price * self.quantity

    # Runs after 'price' changes. The Change carries the old and new values,
    # so we can compare them. This replaces the by-hand tracking that lived
    # inside the manual setter.
    @watch("price")
    def on_price_changed(self, change: Change):
        if change.new > change.old * 1.5:
            print(f"warning: price jumped {change.old} -> {change.new}")


if __name__ == "__main__":
    cart = Cart()
    print(f"initial total: {cart.total}")
    cart.price = 16      # 16 > 10 * 1.5, so the @watch callback warns
    cart.quantity = 3
    print(f"final total: {cart.total}")

The price jump warning that lived inside the manual setter in Step 1 is now a self-contained method. Because the Change gives us both change.old and change.new, we can compare them directly. A @watch callback only runs when the value actually changes. Setting a property to its current value does not trigger it.

Note

To watch more than one property, stack several @watch decorators on the same method, one per property.

Step 4: Run side effects with @effect

An effect() runs whenever any of the properties it lists changes. Unlike @watch it receives no Change; it is simply called with self so it can react to the new state.

from PySide6.QtCore import QObject
from PySide6.QtQmlFeatures import auto_properties, computed, watch, effect, Change


@auto_properties
class Cart(QObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.price = 10
        self.quantity = 2

    @computed("price", "quantity")
    def total(self) -> int:
        return self.price * self.quantity

    @watch("price")
    def on_price_changed(self, change: Change):
        if change.new > change.old * 1.5:
            print(f"warning: price jumped {change.old} -> {change.new}")

    # Runs after price or quantity changes. Unlike @watch it gets no Change;
    # it just reacts to the new state. This replaces the _log_state() calls
    # that the manual setters had to make by hand.
    @effect("price", "quantity")
    def log_state(self):
        print(f"cart: {self.price} x {self.quantity}")


if __name__ == "__main__":
    cart = Cart()
    print(f"initial total: {cart.total}")
    cart.price = 16
    cart.quantity = 3
    print(f"final total: {cart.total}")

The _log_state calls that Step 1 had to sprinkle inside both setters are now a single @effect("price", "quantity") method. Use @watch when you need the before/after values and @effect when you only need to react to the new state. See Comparison: @watch vs @effect in the module reference for a side-by-side comparison.

Run any of these steps directly to see the reactions on the console:

$ python steps/04-effect.py
initial total: 20
warning: price jumped 10 -> 16
cart: 16 x 2
cart: 16 x 3
final total: 48

Step 5: Bind it all from QML

So far the cart has been driven from Python. The real payoff is that the generated properties are ordinary Q_PROPERTY objects, so QML can both read and write them, and the observers fire on changes written from QML too.

Add the @QmlElement decorator on top of @auto_properties and define the QML_IMPORT_NAME / QML_IMPORT_MAJOR_VERSION variables. Stack the decorators so @auto_properties runs first (innermost): it must add the generated properties to the QMetaObject before @QmlElement registers the type.

import sys
from pathlib import Path

from PySide6.QtCore import QObject
from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine, QmlElement
from PySide6.QtQmlFeatures import auto_properties, computed, watch, effect, Change

# To be used on the @QmlElement decorator.
QML_IMPORT_NAME = "Shop"
QML_IMPORT_MAJOR_VERSION = 1


# Stack the decorators so @auto_properties runs first (innermost): it must
# add the generated Q_PROPERTYs to the QMetaObject before @QmlElement
# registers the type with the QML engine.
@QmlElement
@auto_properties
class Cart(QObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.price = 10
        self.quantity = 2

    @computed("price", "quantity")
    def total(self) -> int:
        return self.price * self.quantity

    @watch("price")
    def on_price_changed(self, change: Change):
        if change.new > change.old * 1.5:
            print(f"warning: price jumped {change.old} -> {change.new}")

    @effect("price", "quantity")
    def log_state(self):
        print(f"cart: {self.price} x {self.quantity}")


if __name__ == "__main__":
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()
    engine.addImportPath(sys.path[0])
    qml_file = Path(__file__).parent / "cart.qml"
    engine.load(qml_file)
    if not engine.rootObjects():
        sys.exit(-1)
    exit_code = app.exec()
    del engine
    sys.exit(exit_code)

The QML file reads total and writes price and quantity:

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
import Shop

ApplicationWindow {
    visible: true
    width: 320
    height: 220
    title: "Reactive Cart"

    Cart { id: cart }

    ColumnLayout {
        anchors.centerIn: parent
        spacing: 12

        // Reads the @computed 'total'. It re-evaluates automatically whenever
        // price or quantity changes, because each fires its notify signal.
        Label {
            text: `Total: ${cart.total}`
            font.pixelSize: 24
            Layout.alignment: Qt.AlignHCenter
        }

        RowLayout {
            Label { text: "Price:" }
            // Writing cart.price runs the generated setter, which fires the
            // @watch and @effect callbacks and invalidates 'total'.
            SpinBox {
                from: 1
                to: 999
                value: cart.price
                onValueModified: cart.price = value
            }
        }

        RowLayout {
            Label { text: "Quantity:" }
            SpinBox {
                from: 1
                to: 99
                value: cart.quantity
                onValueModified: cart.quantity = value
            }
        }
    }
}

When you drag a SpinBox, QML writes cart.price (or cart.quantity). That runs the generated setter, which fires the @watch and @effect callbacks on the Python side, invalidates total, and emits the notify signal so the Total label re-evaluates, all without a single hand-written signal connection.

Step 6: Load the view from Python with load_qml_component

Step 5 let QML own the object: Cart { id: cart } instantiates the Python type from QML, and QQmlApplicationEngine.load() brings the whole UI up. This last step shows the mirror image. The reactive Cart stays in Python, and we pull a QML view into Python with load_qml_component, then feed the reactive values into it.

This time there is no @QmlElement on the Cart: QML never creates it. The model is a plain Python object, and a small display-only QML component is loaded and driven from Python.

import sys

from PySide6.QtCore import QObject, QTimer
from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine
from PySide6.QtQmlFeatures import (auto_properties, computed, watch, effect,
                                   Change, load_qml_component)


# The reactive model is unchanged from Step 4: no @QmlElement this time,
# because the model stays in Python and QML never instantiates it.
@auto_properties
class Cart(QObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.price = 10
        self.quantity = 2

    @computed("price", "quantity")
    def total(self) -> int:
        return self.price * self.quantity

    @watch("price")
    def on_price_changed(self, change: Change):
        if change.new > change.old * 1.5:
            print(f"warning: price jumped {change.old} -> {change.new}")

    @effect("price", "quantity")
    def log_state(self):
        print(f"cart: {self.price} x {self.quantity}")


if __name__ == "__main__":
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()

    # This time the reactive model lives in Python, not in QML.
    cart = Cart()

    # Pull the QML view into Python with load_qml_component() and create an
    # instance. 'view' is a Pythonic wrapper whose QML properties are plain
    # attributes, so we can assign to view.total, view.price, etc.
    view_factory = load_qml_component(engine, "cartview.qml")
    view = view_factory.create()

    # Push the reactive values into the loaded QML view. Connecting to the
    # input notify signals is enough: reading cart.total recomputes the
    # @computed value on demand.
    def sync():
        view.price = cart.price
        view.quantity = cart.quantity
        view.total = cart.total

    cart.priceChanged.connect(sync)
    cart.quantityChanged.connect(sync)
    sync()

    # Drive the reactive model from Python. Each assignment runs the @watch
    # and @effect callbacks (console output) and, through sync(), updates the
    # QML view that was loaded from Python.
    def tick():
        cart.price += 2
        if cart.price > 30:
            cart.price = 10
            cart.quantity = cart.quantity % 5 + 1

    timer = QTimer()
    timer.timeout.connect(tick)
    timer.start(500)

    exit_code = app.exec()
    del engine
    sys.exit(exit_code)

load_qml_component returns a factory; calling create() on it instantiates the component and returns a Pythonic wrapper whose QML properties are plain attributes. That is why view.total and view.price can be assigned directly from sync().

The QML view carries no logic of its own, just three properties that Python writes to:

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

// A pure display component. It has no logic of its own: Python loads it with
// load_qml_component(), creates it, and pushes the reactive cart's values
// into these three plain properties.
ApplicationWindow {
    property int price: 0
    property int quantity: 0
    property int total: 0

    visible: true
    width: 320
    height: 220
    title: "Reactive Cart (loaded from Python)"

    ColumnLayout {
        anchors.centerIn: parent
        spacing: 12

        Label {
            text: `Total: ${total}`
            font.pixelSize: 24
            Layout.alignment: Qt.AlignHCenter
        }

        Label {
            text: `price = ${price},  quantity = ${quantity}`
            Layout.alignment: Qt.AlignHCenter
        }
    }
}

A QTimer nudges cart.price from Python. Each change runs the @watch and @effect callbacks (printed to the console) exactly as before, and sync() reads the recomputed total and pushes it into the QML view loaded from Python. The reactive decorators and load_qml_component work together: the decorators keep the model consistent, while load_qml_component lets Python own and drive the view.

Note

We connect to priceChanged and quantityChanged (the input notify signals) rather than totalChanged. A @computed value is lazy: total is recomputed when it is read, so sync() reads cart.total on demand after either input changes.

Note

load_qml_component is part of the PySide6.QtQmlFeatures technical preview. See the PySide6.QtQmlFeatures module reference for its full description.

Where to go next

For the full description of each decorator, the Change type, @auto_properties, @computed, @watch, and @effect, as well as load_qml_component, see the PySide6.QtQmlFeatures module reference.