or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compatibility.mdcore-package.mddevelopment-tools.mdindex.mdqt-modules.mduic-module.md
tile.json

tessl/pypi-qtpy

Provides an abstraction layer on top of the various Qt bindings (PyQt5/6 and PySide2/6).

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/qtpy@2.4.x

To install, run

npx @tessl/cli install tessl/pypi-qtpy@2.4.0

index.mddocs/

QtPy

QtPy is a small abstraction layer that provides a unified API for writing applications using any of the major Python Qt bindings (PyQt5, PySide2, PyQt6, and PySide6). It allows developers to write Qt applications using a single API regardless of which Qt binding is installed, making code more portable and easier to maintain across different Qt environments.

Package Information

  • Package Name: QtPy
  • Language: Python
  • Installation: pip install qtpy

Core Imports

import qtpy

Import Qt modules:

from qtpy import QtCore, QtWidgets, QtGui

Import specific classes:

from qtpy.QtWidgets import QApplication, QWidget, QPushButton
from qtpy.QtCore import Signal, Slot, QTimer

Basic Usage

import sys
from qtpy.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
from qtpy.QtCore import Signal, Slot

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QtPy Example")
        
        # Create layout and button
        layout = QVBoxLayout()
        button = QPushButton("Click me!")
        button.clicked.connect(self.on_button_clicked)
        
        layout.addWidget(button)
        self.setLayout(layout)
    
    @Slot()
    def on_button_clicked(self):
        print("Button clicked!")

# Create and run application
app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec()

Architecture

QtPy's design enables seamless Qt binding compatibility:

  • Automatic Binding Detection: Automatically selects the first available Qt binding (PyQt5, PySide2, PyQt6, or PySide6)
  • Environment Control: Can be controlled via QT_API environment variable for explicit binding selection
  • Unified Module Interface: All Qt modules are accessible through qtpy.QtModule imports regardless of underlying binding
  • Version Compatibility: Handles differences between Qt5/Qt6 and PyQt/PySide automatically
  • Error Management: Comprehensive error classes for different binding and module availability scenarios

Capabilities

Core Package Interface

Main QtPy package constants, exception classes, and binding information that provide the foundation for Qt binding abstraction and compatibility management.

__version__: str
API_NAME: str
API: str
QT_VERSION: str | None
PYQT_VERSION: str | None
PYSIDE_VERSION: str | None
QT5: bool
QT6: bool
PYQT5: bool
PYQT6: bool
PYSIDE2: bool
PYSIDE6: bool

Core Package

Qt Module Wrappers

Unified access to all major Qt modules that automatically import from the appropriate underlying binding. These modules provide the complete Qt API through a consistent interface.

import qtpy.QtCore
import qtpy.QtWidgets
import qtpy.QtGui
import qtpy.QtNetwork
import qtpy.QtMultimedia
# ... and 40+ other Qt modules

Qt Modules

Compatibility Utilities

Cross-binding compatibility functions for file dialogs, text processing, object lifecycle management, and QVariant handling that smooth over differences between Qt bindings.

def is_text_string(obj) -> bool: ...
def to_text_string(obj, encoding=None) -> str: ...
def getopenfilename(parent=None, caption='', basedir='', filters='', selectedfilter='', options=None): ...
def isalive(obj) -> bool: ...

Compatibility

UIC Module

UI file loading and compilation functionality for working with Qt Designer UI files. Provides cross-binding compatibility for loading UI files at runtime and generating form classes.

def loadUi(uifile: str, baseinstance=None, workingDirectory: str | None = None): ...
def loadUiType(uifile: str, from_imports: bool = False): ...
class UiLoader: ...

UIC Module

Development Tools

Command-line interface and utilities for IDE integration, type checking configuration, and development workflow support with mypy and Pyright.

def print_version() -> None: ...
def get_api_status() -> dict: ...
def generate_mypy_args() -> str: ...
def generate_pyright_config_json() -> str: ...

Development Tools

Types

Exception Classes

class PythonQtError(RuntimeError):
    """Generic error superclass for QtPy."""

class PythonQtWarning(RuntimeWarning):
    """Warning class for QtPy."""

class PythonQtValueError(ValueError):
    """Error raised if an invalid QT_API is specified."""

class QtBindingsNotFoundError(PythonQtError, ImportError):
    """Error raised if no bindings could be found."""

class QtModuleNotFoundError(ModuleNotFoundError, PythonQtError):
    """Raised when a Python Qt binding submodule is not installed/supported."""

class QtModuleNotInstalledError(QtModuleNotFoundError):
    """Raise when a module is supported by the binding, but not installed."""

API Constants

QT_API: str  # Environment variable name
PYQT5_API: list[str]  # ["pyqt5"]
PYQT6_API: list[str]  # ["pyqt6"]
PYSIDE2_API: list[str]  # ["pyside2"]
PYSIDE6_API: list[str]  # ["pyside6"]
API_NAMES: dict[str, str]  # Mapping of API names to display names

# Version minimums
QT5_VERSION_MIN: str
QT6_VERSION_MIN: str
PYQT5_VERSION_MIN: str
PYQT6_VERSION_MIN: str
PYSIDE2_VERSION_MIN: str
PYSIDE6_VERSION_MIN: str