0
# QtPy
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: QtPy
7
- **Language**: Python
8
- **Installation**: `pip install qtpy`
9

10
## Core Imports
11

12
```python
13
import qtpy
14
```
15

16
Import Qt modules:
17

18
```python
19
from qtpy import QtCore, QtWidgets, QtGui
20
```
21

22
Import specific classes:
23

24
```python
25
from qtpy.QtWidgets import QApplication, QWidget, QPushButton
26
from qtpy.QtCore import Signal, Slot, QTimer
27
```
28

29
## Basic Usage
30

31
```python
32
import sys
33
from qtpy.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout
34
from qtpy.QtCore import Signal, Slot
35

36
class MainWindow(QWidget):
37
    def __init__(self):
38
        super().__init__()
39
        self.setWindowTitle("QtPy Example")
40
        
41
        # Create layout and button
42
        layout = QVBoxLayout()
43
        button = QPushButton("Click me!")
44
        button.clicked.connect(self.on_button_clicked)
45
        
46
        layout.addWidget(button)
47
        self.setLayout(layout)
48
    
49
    @Slot()
50
    def on_button_clicked(self):
51
        print("Button clicked!")
52

53
# Create and run application
54
app = QApplication(sys.argv)
55
window = MainWindow()
56
window.show()
57
app.exec()
58
```
59

60
## Architecture
61

62
QtPy's design enables seamless Qt binding compatibility:
63

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

70
## Capabilities
71

72
### Core Package Interface
73

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

76
```python { .api }
77
__version__: str
78
API_NAME: str
79
API: str
80
QT_VERSION: str | None
81
PYQT_VERSION: str | None
82
PYSIDE_VERSION: str | None
83
QT5: bool
84
QT6: bool
85
PYQT5: bool
86
PYQT6: bool
87
PYSIDE2: bool
88
PYSIDE6: bool
89
```
90

91
[Core Package](./core-package.md)
92

93
### Qt Module Wrappers
94

95
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.
96

97
```python { .api }
98
import qtpy.QtCore
99
import qtpy.QtWidgets
100
import qtpy.QtGui
101
import qtpy.QtNetwork
102
import qtpy.QtMultimedia
103
# ... and 40+ other Qt modules
104
```
105

106
[Qt Modules](./qt-modules.md)
107

108
### Compatibility Utilities
109

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

112
```python { .api }
113
def is_text_string(obj) -> bool: ...
114
def to_text_string(obj, encoding=None) -> str: ...
115
def getopenfilename(parent=None, caption='', basedir='', filters='', selectedfilter='', options=None): ...
116
def isalive(obj) -> bool: ...
117
```
118

119
[Compatibility](./compatibility.md)
120

121
### UIC Module
122

123
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.
124

125
```python { .api }
126
def loadUi(uifile: str, baseinstance=None, workingDirectory: str | None = None): ...
127
def loadUiType(uifile: str, from_imports: bool = False): ...
128
class UiLoader: ...
129
```
130

131
[UIC Module](./uic-module.md)
132

133
### Development Tools
134

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

137
```python { .api }
138
def print_version() -> None: ...
139
def get_api_status() -> dict: ...
140
def generate_mypy_args() -> str: ...
141
def generate_pyright_config_json() -> str: ...
142
```
143

144
[Development Tools](./development-tools.md)
145

146
## Types
147

148
### Exception Classes
149

150
```python { .api }
151
class PythonQtError(RuntimeError):
152
    """Generic error superclass for QtPy."""
153

154
class PythonQtWarning(RuntimeWarning):
155
    """Warning class for QtPy."""
156

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

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

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

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

170
### API Constants
171

172
```python { .api }
173
QT_API: str  # Environment variable name
174
PYQT5_API: list[str]  # ["pyqt5"]
175
PYQT6_API: list[str]  # ["pyqt6"]
176
PYSIDE2_API: list[str]  # ["pyside2"]
177
PYSIDE6_API: list[str]  # ["pyside6"]
178
API_NAMES: dict[str, str]  # Mapping of API names to display names
179

180
# Version minimums
181
QT5_VERSION_MIN: str
182
QT6_VERSION_MIN: str
183
PYQT5_VERSION_MIN: str
184
PYQT6_VERSION_MIN: str
185
PYSIDE2_VERSION_MIN: str
186
PYSIDE6_VERSION_MIN: str
187
```