pyqt

name	pyqt
description	[Applies to: **/*.py] Enforce modern, maintainable, and performant PyQt application development standards by leveraging Qt Designer, Model-View architecture, and responsive threading.
source	cursor_mdc

PyQt Best Practices

This guide outlines essential practices for building robust, scalable, and maintainable PyQt applications. Adhere to these rules for consistent, high-quality code.

1. UI Design: Qt Designer & Dynamic Loading

Always design your UI visually with Qt Designer (or Qt Design Studio). Keep the generated .ui files pristine. Load them dynamically at runtime or integrate the pyuic-generated code via inheritance without modification. This separates design from logic and simplifies UI updates.

❌ BAD: Hand-editing pyuic-generated files

# ui_mainwindow.py (DO NOT EDIT THIS FILE DIRECTLY)
# This file was generated by pyuic6...
class Ui_MainWindow(object):
    def setupUi(self, MainWindow):
        # ... generated code ...
        self.my_custom_button.clicked.connect(self.my_logic_function) # Added here

✅ GOOD: Dynamic loading with QUiLoader (PyQt6)

from PyQt6.QtWidgets import QApplication, QWidget
from PyQt6.uic import loadUi

class MyMainWindow(QWidget):
    def __init__(self):
        super().__init__()
        loadUi("mainwindow.ui", self) # Load UI dynamically
        self.my_button.clicked.connect(self._on_button_clicked)

    def _on_button_clicked(self):
        print("Button clicked!")

if __name__ == "__main__":
    app = QApplication([])
    window = MyMainWindow()
    window.show()
    app.exec()

✅ GOOD: Single inheritance with pyuic-generated code

# ui_mainwindow.py (Generated by `pyuic6 -o ui_mainwindow.py mainwindow.ui`)
# DO NOT EDIT THIS FILE.
from PyQt6 import QtWidgets # ... other imports ...
class Ui_MainWindow(object):
    def setupUi(self, MainWindow):
        # ... generated UI setup code ...
        pass # No signal connections here

# main.py (Your application logic)
from PyQt6.QtWidgets import QApplication, QMainWindow
from ui_mainwindow import Ui_MainWindow # Import generated UI

class MyMainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.ui = Ui_MainWindow()
        self.ui.setupUi(self) # Set up the UI on this window
        self.ui.my_button.clicked.connect(self._on_button_clicked)

    def _on_button_clicked(self):
        print("Button clicked from inherited UI!")

if __name__ == "__main__":
    app = QApplication([])
    window = MyMainWindow()
    window.show()
    app.exec()

2. Component Architecture: Model-View Separation

For any data-driven UI (lists, tables, trees), adopt the Model-View architecture. This decouples data management from UI presentation, leading to cleaner, more scalable code.

❌ BAD: Storing data directly in widgets

from PyQt6.QtWidgets import QListWidget, QListWidgetItem
# ...
self.my_list_widget = QListWidget()
self.my_list_widget.addItem("Item 1")
self.my_list_widget.addItem("Item 2")
# To update: self.my_list_widget.item(0).setText("New Item 1") # Tedious

✅ GOOD: Custom QAbstractListModel for data

from PyQt6.QtCore import QAbstractListModel, QModelIndex, Qt
from PyQt6.QtWidgets import QListView, QApplication

class MyListModel(QAbstractListModel):
    def __init__(self, data=None):
        super().__init__()
        self._data = data or []

    def data(self, index: QModelIndex, role: int):
        if role == Qt.ItemDataRole.DisplayRole:
            return self._data[index.row()]
        return None

    def rowCount(self, parent: QModelIndex):
        return len(self._data)

    def add_item(self, item: str):
        self.beginInsertRows(QModelIndex(), len(self._data), len(self._data))
        self._data.append(item)
        self.endInsertRows()

# ... in your QMainWindow or QWidget
# self.my_list_view = QListView()
# self.model = MyListModel(["Initial Item 1", "Initial Item 2"])
# self.my_list_view.setModel(self.model)
# self.model.add_item("New Item from Logic") # Model updates view automatically

3. Asynchronous Operations: Keep UI Responsive

Never block the UI thread with long-running tasks. Use QThreadPool with QRunnable or QThread for background processing. Emit signals from worker threads to update the UI on the main thread.

❌ BAD: Blocking UI thread

import time
from PyQt6.QtWidgets import QPushButton, QLabel
# ...
def on_heavy_button_clicked(self):
    self.status_label.setText("Processing...")
    time.sleep(5) # UI freezes for 5 seconds
    self.status_label.setText("Done!")

✅ GOOD: Offload to QThreadPool

from PyQt6.QtCore import QRunnable, QThreadPool, pyqtSignal, QObject
from PyQt6.QtWidgets import QPushButton, QLabel, QApplication, QWidget
import time

class WorkerSignals(QObject):
    finished = pyqtSignal()
    result = pyqtSignal(str)

class Worker(QRunnable):
    def __init__(self, task_id):
        super().__init__()
        self.signals = WorkerSignals()
        self.task_id = task_id

    def run(self):
        time.sleep(2) # Simulate heavy work
        self.signals.result.emit(f"Task {self.task_id} completed.")
        self.signals.finished.emit()

class MyWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.threadpool = QThreadPool()
        self.button = QPushButton("Start Heavy Task", self)
        self.label = QLabel("Ready", self)
        self.button.clicked.connect(self._start_task)
        # ... layout setup ...

     ():
        .label.setText()
        worker = Worker(time.time()) 
        worker.signals.result.connect(.label.setText)
        worker.signals.finished.connect(: ())
        .threadpool.start(worker)

 __name__ == :
    app = QApplication([])
    window = MyWindow()
    window.show()
    app.()

4. Communication: Signals & Slots

Leverage Qt's powerful signals and slots mechanism for decoupled communication between UI components and business logic.

❌ BAD: Direct method calls for UI events

# In MainWindow
self.login_button.clicked.connect(self.login_manager.authenticate) # login_manager is tightly coupled

✅ GOOD: Decoupled signals and slots

from PyQt6.QtCore import pyqtSignal, QObject
# ...
class LoginManager(QObject):
    login_successful = pyqtSignal(str)
    login_failed = pyqtSignal(str)

    def authenticate(self, username, password):
        if username == "user" and password == "pass":
            self.login_successful.emit("Welcome!")
        else:
            self.login_failed.emit("Invalid credentials.")

# In MainWindow
# self.login_manager = LoginManager()
# self.login_manager.login_successful.connect(self.show_dashboard)
# self.login_manager.login_failed.connect(self.display_error)
# self.login_button.clicked.connect(lambda: self.login_manager.authenticate(self.user_input.text(), self.pass_input.text()))

5. Code Organization & Naming

Follow Pythonic naming conventions (CamelCase for Qt classes, snake_case for methods/variables). Organize code into logical modules (e.g., ui/, models/, workers/). Use Qt resource files (.qrc) for icons, images, and stylesheets.

❌ BAD: Inconsistent naming, monolithic files

# myapp.py
class my_main_window(QtWidgets.QMainWindow): # Incorrect class name
    def __init__(self):
        self.MyButton = QtWidgets.QPushButton() # Incorrect variable name
        # ... all logic here ...

✅ GOOD: Consistent naming, modular structure

# main.py
from PyQt6.QtWidgets import QApplication
from my_app.ui.main_window import MainWindow # Separate UI module

if __name__ == "__main__":
    app = QApplication([])
    main_window = MainWindow()
    main_window.show()
    app.exec()

# my_app/ui/main_window.py
from PyQt6.QtWidgets import QMainWindow
# ...
class MainWindow(QMainWindow): # CamelCase for Qt classes
    def __init__(self):
        super().__init__()
        self._setup_ui() # Private helper method
        self._connect_signals()

    def _on_button_clicked(self): # snake_case for methods
        pass

# my_app/resources.qrc (compiled to my_app/resources_rc.py)
# <RCC>
#   <qresource prefix="/icons">
#     <file>icon.png</file>
#   </qresource>
# </RCC>
# Use: self.setWindowIcon(QIcon(":/icons/icon.png"))

6. Styling & Theming

Use Qt's stylesheet system (CSS-like .qss files) for styling. This allows for easy theming (e.g., dark mode) without modifying Python code.

❌ BAD: Hardcoding styles in Python

self.my_button.setStyleSheet("background-color: red; color: white;") # Hardcoded

✅ GOOD: External stylesheets

# styles.qss
QPushButton {
    background-color: #2196F3; /* Blue */
    color: white;
    border: none;
    padding: 8px 16px;
    border-radius: 4px;
}
QPushButton:hover {
    background-color: #1976D2; /* Darker Blue */
}

# In main.py or MainWindow __init__
with open("styles.qss", "r") as f:
    _stylesheet = f.read()
app.setStyleSheet(_stylesheet) # Apply globally
# Or self.my_widget.setStyleSheet(_stylesheet) # Apply locally

7. Type Hints

Always use Python type hints for improved readability, maintainability, and static analysis.

❌ BAD: Untyped code

def process_data(data):
    # ...

✅ GOOD: Type-hinted code

from typing import List, Tuple
from PyQt6.QtCore import QModelIndex

def process_data(data: List[Tuple[bool, str]]) -> List[str]:
    # ...
    return [item[1] for item in data]

def data(self, index: QModelIndex, role: int) -> str | None:
    # ...