Qt.py 2.0.3
Python compatibility wrapper around Qt5 and Qt6 bindings - PySide2, PySide6, PyQt5 and PyQt6.
License: MIT
Requires Python: >=3.7

<img width=260 src=https://raw.githubusercontent.com/mottosso/Qt.py/master/logo.svg>

[![Downloads](https://pepy.tech/badge/qt-py)](https://pepy.tech/project/qt-py)
[![Run Tests](https://github.com/mottosso/Qt.py/actions/workflows/run-tests.yml/badge.svg)](https://github.com/mottosso/Qt.py/actions)
[![PyPI version](https://badge.fury.io/py/Qt.py.svg)](https://pypi.python.org/pypi/Qt.py)
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/qt.py/badges/version.svg)](https://anaconda.org/conda-forge/qt.py)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Qt-py/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)

Qt.py enables you to write software that runs on any of the 4 supported bindings - PySide6, PyQt6, PySide2, PyQt5.

<br>

##### News

| Date     | Version   | Event
|:---------|:----------|:----------
| Jan 2025 | [2.0.0][] | Dropped support for Qt 4 and python versions older than 3.7
| May 2024 | [1.4.1][] | Added support for Qt 6
| Jan 2024 | [1.3.9][] | Run CI on Github Actions, instead of Travis CI.
| Sep 2020 | [1.3.0][] | Stability improvements and greater ability for `QtCompat.wrapInstance` to do its job
| Jun 2019 | [1.2.1][] | Bugfixes and [additional members](https://github.com/mottosso/Qt.py/releases/tag/1.2.0)
| Jan 2018 | [1.1.0][] | Adds new test suite, new members
| Mar 2017 | [1.0.0][] | Increased safety, **backwards incompatible**
| Sep 2016 | [0.6.9][] | Stable release
| Sep 2016 | [0.5.0][] | Alpha release of `--convert`
| Jun 2016 | [0.2.6][] | First release of Qt.py

- [More details](https://github.com/mottosso/Qt.py/releases).

[0.2.6]: https://github.com/mottosso/Qt.py/releases/tag/0.2.6
[0.5.0]: https://github.com/mottosso/Qt.py/releases/tag/0.5.0
[0.6.9]: https://github.com/mottosso/Qt.py/releases/tag/0.6.9
[1.0.0]: https://github.com/mottosso/Qt.py/releases/tag/1.0.0
[1.1.0]: https://github.com/mottosso/Qt.py/releases/tag/1.1.0
[1.2.1]: https://github.com/mottosso/Qt.py/releases/tag/1.2.1
[1.3.0]: https://github.com/mottosso/Qt.py/releases/tag/1.3.0
[1.3.9]: https://github.com/mottosso/Qt.py/releases/tag/1.3.9
[1.4.1]: https://github.com/mottosso/Qt.py/releases/tag/1.4.1

##### Guides

- [Qt 6 Transition Guide](#qt-6-transition-guide)
- [Developing with Qt.py](https://fredrikaverpil.github.io/blog/2016/07/25/developing-with-qtpy/)
- [Dealing with Maya 2017 and PySide2](https://fredrikaverpil.github.io/blog/2016/07/25/dealing-with-maya-2017-and-pyside2/)
- [Vendoring Qt.py](https://fredrikaverpil.github.io/blog/2017/05/04/vendoring-qtpy/)
- [Udemy Course](https://www.udemy.com/python-for-maya/learn/v4/t/lecture/6027394)
- [PythonBytes #77](https://pythonbytes.fm/episodes/show/77/you-don-t-have-to-be-a-workaholic-to-win) (Starts at 5:00)

##### Table of contents

- [Project goals](#project-goals)
- [Install](#install)
- [Usage](#usage)
- [Documentation](#documentation)
  - [Environment Variables](#environment-variables)
  - [Subset](#subset)
  - [Branch binding-specific code](#branch-binding-specific-code)
  - [Override preferred choice](#override-preferred-choice)
  - [QtSiteConfig.py](#qtsiteconfigpy)
  - [Compile Qt Designer files](#compile-qt-designer-files)
  - [Loading Qt Designer files](#loading-qt-designer-files)
- [Rules](#rules)
- [How it works](#how-it-works)
- [Known problems](#known-problems)
- [Who's using Qt.py?](#whos-using-qtpy)
- [Projects using Qt.py](#projects-using-qtpy)
- [Projects similar to Qt.py](#projects-similar-to-qtpy)
- [Developer guide](#developer-guide)

<br>
<br>
<br>

### Project goals

Write once, run in any binding.

Qt.py was born in the film and visual effects industry to address the growing need for software capable of running with more than one flavor of the Qt bindings for Python - PySide6, PySide2, PyQt6 and PyQt5.

| Goal                                 | Description
|:-------------------------------------|:---------------
| *Support co-existence*               | Qt.py should not affect other bindings running in same interpreter session.
| *Build for one, run with all*        | Code written with Qt.py should run on any binding.
| *Explicit is better than implicit*   | Differences between bindings should be visible to you.

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details.

<br>
<br>
<br>

### Install

Qt.py is a single file and can either be [copy/pasted](https://raw.githubusercontent.com/mottosso/Qt.py/master/Qt.py) into your project, [downloaded](https://github.com/mottosso/Qt.py/archive/master.zip) as-is, cloned as-is or installed via `pip` or `conda`.

```bash
# From PyPI
$ pip install Qt.py
```

```bash
# From Anaconda
$ conda config --add channels conda-forge
$ conda install qt.py
```

- Pro tip: **Never use the latest commit for production**. Instead, use [the latest release](https://github.com/mottosso/Qt.py/releases). That way, when you read bug reports or make one for yourself you will be able to match a version with the problem without which you will not know which fixes apply to you nor would we be able to help you. Installing via pip or conda as above ensures you are provided the latest *stable* release. Unstable releases are suffixed with a `.b`, e.g. `1.1.0.b3`.
- Pro tip: Supports [vendoring](https://fredrikaverpil.github.io/blog/2017/05/04/vendoring-qtpy/)

<br>
<br>
<br>

### Usage

Use Qt.py as you would use PySide6.

![image](https://cloud.githubusercontent.com/assets/2152766/15653248/b5ce298e-2683-11e6-8c0c-f041ecae203d.png)

```python
import sys
from Qt import QtWidgets, QtCompat

app = QtWidgets.QApplication(sys.argv)
button = QtWidgets.QPushButton("Hello World")
button.show()
QtCompat.QApplication.exec_()
```

- Also see [/examples](examples)

<br>
<br>
<br>

### Documentation

All members of `Qt` stem directly from those available via PySide6, along with these additional members.

| Attribute               | Returns     | Description
|:------------------------|:------------|:------------
| `__version__`           | `str`       | Version of this project
| `__binding__`           | `str`       | A string reference to binding currently in use
| `__qt_version__`        | `str`       | Reference to version of Qt, such as Qt 5.6.1
| `__binding_version__`   | `str`       | Reference to version of binding, such as PySide 1.2.6

**Example**

```python
>>> from Qt import __binding__
>>> __binding__
'PyQt5'
```

### Compatibility

Qt.py also provides compatibility wrappers for critical functionality that differs across bindings, these can be found in the added `QtCompat` submodule.

| Attribute                                 | Returns     | Description
|:------------------------------------------|:------------|:------------
| `loadUi(uifile=str, baseinstance=QWidget)`| `QObject`   | Minimal wrapper of PyQt6.loadUi and PySide6 equivalent
| `translate(...)`        					| `function`  | Compatibility wrapper around [QCoreApplication.translate][]
| `wrapInstance(addr=long, type=QObject)`   | `QObject`   | Wrapper around `shiboken6.wrapInstance` and PyQt equivalent
| `getCppPointer(object=QObject)`           | `long`      | Wrapper around `shiboken6.getCppPointer` and PyQt equivalent
| `isValid(object=QObject)`                 | `bool`      | Wrapper around `shiboken6.isValid` and PyQt equivalent
| `dataChanged(topLeft=QModelIndex, bottomRight=QModelIndex, roles=[])` | `None` | Wrapper around `QtCore.QAbstractItemModel.dataChanged.emit`

[QCoreApplication.translate]: https://doc.qt.io/qt-5/qcoreapplication.html#translate

**Example**

```python
>>> from Qt import QtCompat
>>> QtCompat.loadUi
```

#### Class specific compatibility objects

> **Note:** Most of these are for Qt4 and Qt5 compatibility. With 2.0 dropping support for Qt4 many of them are no longer needed, but we are leaving them in for backwards compatibility.

Between Qt4 and Qt5 there have been many classes and class members that are obsolete. Under Qt.QtCompat there are many classes with names matching the classes they provide compatibility functions. These will match the PySide2 naming convention.

```python
from Qt import QtCore, QtWidgets, QtCompat
header = QtWidgets.QHeaderView(QtCore.Qt.Horizontal)
QtCompat.QHeaderView.setSectionsMovable(header, False)
movable = QtCompat.QHeaderView.sectionsMovable(header)
```

This also covers inconsistencies between bindings. For example PyQt4's QFileDialog matches Qt4's return value of the selected. While all other bindings return the selected filename and the file filter the user used to select the file. `Qt.QtCompat.QFileDialog` ensures that getOpenFileName(s) and getSaveFileName always return the tuple.

<br>

##### Environment Variables

These are the publicly facing environment variables that in one way or another affect the way Qt.py is run.

| Variable                  | Type  | Description
|:--------------------------|:------|:----------
| QT_PREFERRED_BINDING_JSON | str   | Override order and content of binding to try. This can apply per Qt.py namespace.
| QT_PREFERRED_BINDING      | str   | Override order and content of binding to try. Used if QT_PREFERRED_BINDING_JSON does not apply.
| QT_VERBOSE                | bool  | Be a little more chatty about what's going on with Qt.py

<br>

##### Subset (or "common members")

Members of Qt.py is a subset of PySide6. Which means for a member to be made accessible via Qt.py, it will need to (1) be accessible via PySide6 and (2) each of the other supported bindings. This excludes large portions of the Qt framework, including the newly added QtBluetooth and QtQuick3D modules but guarantees that anything you develop with Qt.py will work identically on any binding - PySide2, PySide6, PyQt5 and PyQt6. If you need to use such excluded modules with Qt.py, please see [QtSiteConfig.py](#qtsiteconfigpy).

We call this subset "common members" and these can be generated by running the [tox tests](#running-tests). The membership tests will output all modules and members of each binding into individual JSON files. These JSON files are then compared and a `/.members/common_members.json` file is generated. The contents of the `members` dictionary of this file is copy-pasted into the `_common_members` dictionary of Qt.py. Please note that the script will only use the most up-to-date set of VFX Platform-stipulated software versions.

See the wiki for a breakdown of what members are common across the supported Qt python bindings:
- [Qt.py<1.4](https://github.com/mottosso/Qt.py/wiki/Membership-between-Qt4,Qt5): PySide2, PyQt5, PySide, PyQt4
- [Qt.py=\=1.4.\*](https://github.com/mottosso/Qt.py/wiki/Membership-between-Qt4,Qt5,Qt6): PySide6, PyQt6, PySide2, PyQt5, PySide, PyQt4
- [Qt.py=\=2.0.\*](https://github.com/mottosso/Qt.py/wiki/Membership-between-Qt5.13,Qt6): PySide6, PyQt6, PySide2, PyQt5. (Minimum Qt version 5.13)

<br>

##### Branch binding-specific code

Some bindings offer features not available in others, you can use `__binding__` to capture those.

```python
if "PySide" in __binding__:
  do_pyside_stuff()
```

<br>

##### Override preferred choice

If your system has multiple choices where one or more is preferred, you can override the preference and order in which they are tried with this environment variable.

```bash
$ set QT_PREFERRED_BINDING=PyQt5  # Windows
$ export QT_PREFERRED_BINDING=PyQt5  # Unix/OSX
$ python -c "import Qt;print(Qt.__binding__)"
PyQt5
```

Constrain available choices and order of discovery by supplying multiple values.

```bash
# Try PyQt5 first and then PySide2, but nothing else.
$ export QT_PREFERRED_BINDING=PyQt5:PySide2
```

Using the OS path separator (`os.pathsep`) which is `:` on Unix systems and `;` on Windows.

If you need to control the preferred choice of a specific vendored Qt.py you can use the `QT_PREFERRED_BINDING_JSON` environment variable instead.

```json
{
    "Qt":["PyQt5"],
    "myproject.vendor.Qt":["PyQt5"],
    "default":["PySide2"]
}
```

This json data forces any code that uses `import Qt` or `import myproject.vendor.Qt` to use PyQt5(`from x import Qt` etc works too, this is based on `__name__` of the Qt.py being imported). Any other imports of a Qt module will use the "default" PySide2 only. If `"default"` is not provided or a Qt.py being used does not support `QT_PREFERRED_BINDING_JSON`, `QT_PREFERRED_BINDING` will be respected.

```bash
# Try PyQt6 first and then PyQt5 for the Qt module name space.
$ export QT_PREFERRED_BINDING_JSON="{"Qt":["PyQt6","PyQt5"]}"
# Use PySide2 for any other Qt module name spaces.
$ export QT_PREFERRED_BINDING=PySide2
```

<br>

##### QtSiteConfig.py

Add or remove members from Qt.py at run-time.

-  [Examples](/examples/QtSiteConfig)

<br>

If you need to expose a module that isn't included in Qt.py by default or wish to remove something from being exposed in Qt.py you can do so by creating a `QtSiteConfig.py` module and making it available to Python.

1. Create a new file `QtSiteConfig.py`
2. Implement `update_members`
3. Expose to Python

```python
# QtSiteConfig.py
def update_members(members):
    """Called by Qt.py at run-time to modify the modules it makes available.

    Arguments:
        members (dict): The members considered by Qt.py
    """
    members.pop("QtCore")
```

Finally, expose the module to Python.

```bash
$ set PYTHONPATH=/path/to
$ python -c "import Qt.QtCore"
ImportError: No module named Qt.QtCore
```

> Linux and MacOS users, replace `set` with `export`

<br>

##### Compile Qt Designer files

> WARNING - ALPHA FUNCTIONALITY<br>
> See [#132](https://github.com/mottosso/Qt.py/pull/132) for details.

`.ui` files compiled via `pyside2-uic` inherently contain traces of PySide2 - e.g. the line `from PySide2 import QtGui`.

In order to use these with Qt.py, or any other binding, one must first erase such traces and replace them with cross-compatible code.

```bash
$ pyside2-uic my_ui.ui -o my_ui.py
$ python -m Qt --convert my_ui.py
# Creating "my_ui_backup.py"..
# Successfully converted "my_ui.py"
```

Now you may use the file as you normally would, with Qt.py

<br>

##### Loading Qt Designer files

The `uic.loadUi` function of PyQt5 and PyQt6 as well as the `QtUiTools.QUiLoader().load` function of PySide6/PySide2 are mapped to a convenience function `loadUi`.

```python
import sys
from Qt import QtCompat, QtWidgets

app = QtWidgets.QApplication(sys.argv)
ui = QtCompat.loadUi(uifile="my.ui")
ui.show()
QtCompat.QApplication.exec_()
```
For `PyQt` bindings it uses their native implementation, whereas for `PySide` bindings it uses our custom implementation borrowed from the [qtpy](https://github.com/spyder-ide/qtpy) project.

`loadUi` has two arguments as opposed to the multiple that PyQt ships with. See [here](https://github.com/mottosso/Qt.py/pull/81) for details - in a nutshell, those arguments differ between PyQt and PySide in incompatible ways.
The second argument is `baseinstance` which allows a ui to be dynamically loaded onto an existing QWidget instance.

```python
QtCompat.loadUi(uifile="my.ui", baseinstance=QtWidgets.QWidget)
```

`uifile` is the string path to the ui file to load.

If `baseinstance` is `None`, the a new instance of the top-level
widget will be created. Otherwise, the user interface is created within
the given `baseinstance`. In this case `baseinstance` must be an
instance of the top-level widget class in the UI file to load, or a
subclass thereof. In other words, if you've created a `QMainWindow`
interface in the designer, `baseinstance` must be a `QMainWindow`
or a subclass thereof, too. You cannot load a `QMainWindow` UI file
with a plain `QWidget` as `baseinstance`.

`loadUi` returns `baseinstance`, if `baseinstance` is provided.
Otherwise it will return the newly created instance of the user interface.

<br>

### Rules

The PyQt and PySide bindings are similar, but not identical. Where there is ambiguity, there must to be a clear direction on which path to take.

**Governing API**

The official [Qt 6 documentation](https://doc.qt.io/qt-6/classes.html) is always right. Where the documentation lacks answers, PySide6 is right.

For example.

```python
# PyQt6 adheres to PySide6 signals and slots
PyQt6.Signal = PyQt6.pyqtSignal
PyQt6.Slot = PyQt6.pyqtSlot
```

**Caveats**

There are cases where Qt.py is not handling incompatibility issues. Please see [`CAVEATS.md`](CAVEATS.md) for more information.

<br>
<br>
<br>

### Known Problems

Send us a pull-request with known problems here!

- [Maya and incompatible bindings on PYTHONPATH](https://github.com/mottosso/Qt.py/issues/146)

<br>
<br>
<br>

### Who's using Qt.py?

Send us a pull-request with your studio here.

- [Atomic Fiction](http://www.atomicfiction.com/)
- [Bläck](http://www.blackstudios.se/)
- [Blur Studio](http://www.blur.com)
- [CGRU](http://cgru.info/)
- [Colorbleed](http://www.colorbleed.nl/)
- [Digital Domain](https://www.digitaldomain.com/)
- [Disney Animation](https://www.disneyanimation.com/)
- [Dreamworks Animation](https://github.com/dreamworksanimation)
- [Epic Games](https://www.epicgames.com/)
- [Fido](http://fido.se/)
- [Framestore](https://framestore.com)
- [ftrack](https://www.ftrack.com/)
- [Futureworks](http://futureworks.in/)
- [Industrial Brothers](http://industrialbrothers.com/)
- [Industriromantik](http://www.industriromantik.se/)
- [Mackevision](http://www.mackevision.com/)
- [Method Studios](http://www.methodstudios.com/)
- [Mikros Image](http://www.mikrosimage.com/)
- [Moonbot Studios](http://moonbotstudios.com/)
- [MPC](http://www.moving-picture.com)
- [Overmind Studios](https://www.overmind-studios.de/)
- [Psyop](http://www.psyop.com/)
- [Raynault VFX](https://www.raynault.com/)
- [Rising Sun Pictures](https://rsp.com.au)
- [Rodeo FX](https://www.rodeofx.com/en/)
- [Sony Pictures Imageworks](http://www.imageworks.com/)
- [Spin VFX](http://www.spinvfx.com/)
- [Weta Digital](https://www.wetafx.co.nz/)
- [GermanTechJobs](https://germantechjobs.de)

Presented at Siggraph 2016, BOF!

![image](https://cloud.githubusercontent.com/assets/2152766/17621229/c2448db2-6089-11e6-915f-0604e5d8c7ee.png)

<br>
<br>
<br>

### Projects using Qt.py

Send us a pull-request with your project here.

- [USD Manager](http://www.usdmanager.org)
- [Cosmos](http://cosmos.toolsfrom.space/)
- [maya-capture-gui](https://github.com/BigRoy/maya-capture-gui)
- [pyblish-lite](https://github.com/pyblish/pyblish-lite)
- [pyvfx-boilerplate](https://github.com/fredrikaverpil/pyvfx-boilerplate)
- [riffle](https://gitlab.com/4degrees/riffle)
- [cmt](https://github.com/chadmv/cmt)
- [PythonForMayaSamples](https://github.com/dgovil/PythonForMayaSamples)
- [Kraken](https://github.com/fabric-engine/Kraken)
- [AFANASY](http://cgru.info/afanasy/afanasy)
- [Syncplay](https://github.com/Syncplay/syncplay)
- [BlenderUpdater](https://github.com/overmindstudios/BlenderUpdater)
- [QtPyConvert](https://github.com/DigitalDomain/QtPyConvert)
- [Pyper](https://gitlab.com/brunoebe/pyper.git)

<br>
<br>
<br>

### Projects similar to Qt.py

Comparison matrix.

| Project       | Audience      | Reference binding | License   | PEP8 |Standalone | PyPI   | Co-existence
|:--------------|:--------------|:------------------|:----------|------|:----------|--------|--------------
| Qt.py         | Film          | PySide2           | MIT       | X    | X         | X      | X
| [jupyter][]   | Scientific    | N/A               | N/A       | X    |           |        |
| [QtPy][]      | Scientific    | N/A               | MIT       |      | X         | X      |
| [pyqode.qt][] | Scientific    | PyQt5             | MIT       | X    |           | X      |
| [QtExt][]     | Film          | N/A               | N/A       |      | X         |        |
| [python_qt_binding][] | Robotics | N/A            | BSD       | X    | X        | X       | X

Also worth mentioning, [pyqt4topyqt5](https://github.com/rferrazz/pyqt4topyqt5); a good starting point for transitioning to Qt.py.

Send us a pull-request with your project here.

[QtPy]: https://github.com/spyder-ide/qtpy
[jupyter]: https://github.com/jupyter/qtconsole/blob/master/qtconsole/qt_loaders.py
[pyqode.qt]: https://github.com/pyQode/pyqode.qt
[QtExt]: https://bitbucket.org/ftrack/qtext
[python_qt_binding]: https://github.com/ros-visualization/python_qt_binding

<br>
<br>
<br>

### Developer Guide

Tests are performed on each aspect of the shim.

- [Functional](tests.py)
- [Caveats](build_caveats.py)
- [Examples](examples)

Each of these are run under..

- Python 3.7
- Python 3.9
- Python 3.10
- Python 3.11

..once for each binding or under a specific binding only.

Each test is run within it's own isolated process, so as to allow an `import` to occur independently from other tests. Process isolation is handled via [nosepipe](https://pypi.python.org/pypi/nosepipe).

Tests that are written at module level are run four times - once per binding - whereas tests written under a specific if-statement are run only for this particular binding.

```python
if binding("PyQt5"):
    def test_something_related_to_pyqt5():
        pass
```

**Code convention**

Below are some of the conventions that used throughout the Qt.py module and tests.

- **Etiquette: PEP8**
    - All code is checked using ruff check and format. Use `tox -e check,format`.
- **Etiquette: Double quotes**
    - " = yes, ' = no.
- **Etiquette: Napoleon docstrings**
    - Any docstrings are made in Google Napoleon format. See [Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for details.
- **Etiquette: Semantic Versioning**
    - This project follows [semantic versioning](http://semver.org).
- **Etiquette: Underscore means private**
    - Anything prefixed with an underscore means that it is internal to Qt.py and not for public consumption.

#### Running tests

Due to the nature of multiple bindings and multiple interpreter support, setting up a development environment in which to properly test your contraptions can be challenging. So here is a guide for how to do just that using **tox**.

**Setup:**

You will need to install python 3.7 or higher. It's recommended that you install
python 3.7, 3.9, 3.10 and 3.11 so you can test all supported versions of python
but tox is configured to allow you to skip test for missing python versions. However
when the tests run on github all versions of python are required to work.

Install tox using pip in your preferred version of python. `pip install tox` For
the rest of this guide it's assumed that you have this version of python added to
your `PATH` env var and can run the command `tox`.

**Running tox**

When running tox, its expected that you are in a terminal and have cd'd into the
root of the git checkout.

To run all tests run the command `tox`. This will run all default tests in order
sequentially. This lets you see all output from each test as it runs. This project
is configured run tests in parallel using `tox -p`. This lets you run all of the
tests much quicker but you only see output if there is a problem.

A successful run should generate output similar to this once finished:
```
  membership-begin: OK (0.16=setup[0.06]+cmd[0.09] seconds)
  membership-py39-PySide5.15: OK (0.38=setup[0.02]+cmd[0.36] seconds)
  membership-py39-PyQt5.15: OK (0.28=setup[0.02]+cmd[0.27] seconds)
  membership-py311-PySide6.5: OK (0.67=setup[0.08]+cmd[0.59] seconds)
  membership-py311-PyQt6.7: OK (0.42=setup[0.14]+cmd[0.28] seconds)
  membership-end: OK (0.17=setup[0.00]+cmd[0.17] seconds)
  test-begin: OK (0.06=setup[0.00]+cmd[0.06] seconds)
  test-py37-PySide5.13-impl: OK (11.03=setup[5.59]+cmd[1.22,4.22] seconds)
  test-py37-PySide5.13-caveats: OK (7.05=setup[5.64]+cmd[1.17,0.24] seconds)
  test-py37-PySide5.13-examples: OK (7.78=setup[5.61]+cmd[1.20,0.61,0.36] seconds)
...
  test-py311-PyQt6.5-impl: OK (9.45=setup[6.81]+cmd[2.64] seconds)
  test-py311-PyQt6.5-caveats: OK (7.09=setup[6.80]+cmd[0.30] seconds)
  test-py311-PyQt6.5-examples: OK (7.86=setup[6.81]+cmd[0.72,0.33] seconds)
  congratulations :) (13.30 seconds)
```

Running all tests is useful for verifying that there are no problems, but when
you run into a problem its useful to only run one or a couple of tests. You can
use the `-e` flag to specify specific test names. When using `-e` you have to
pass specific test names you want to run as a comma separated list. Any of the
test names(text before the `: OK`) listed above can be used.

Running a single test:
```bash
tox -e membership-py311-PySide6.5
```

Running multiple tests:
```bash
tox -e membership-begin,membership-py311-PySide6.5,membership-py311-PyQt6.7,membership-end
```
This would run just those 4 tests.

The membership-begin is used to clean up files left from previous tests.
The next to jobs are used to run specifically configured tests in this case
generating a list of bindings for PySide6 and PyQt6 in python 3.11. The
membership-end job is used to combine the files generated by the previous tests.

The Github Actions are using the same tox configuration to run all of the tests
which means that when the tests pass on your machine, they pass on Github Actions. And everybody wins!

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more of the good stuff.

**Test breakdown**

- Tests starting with `membership-` are used to generate the [common members](#subset) dictionary. These are written into the `/.members` directory.
    - `membership-begin` removes files created by the other membership tests to ensure the new test run doesn't have old data.
    - `membership-*-*` Each test uses a specific version of python and Qt to generate a mapping of members available.
    - `membership-end` combines the data generated by each `membership-*-*` into the final common members dictionary for all Qt versions as well as per-major Qt version. It also creates some reference .md files to make it easy to see all possible members and which bindings implement them.
- Tests starting with `test-` are used to run the testing suite on a specific set of python and Qt.
    - `test-begin` generates files needed to run the other tests.
    - `test-*-*-impl` runs implementation tests defined in test.py.
    - `test-*-*-caveats` tests the code found in [`CAVEATS.md`](CAVEATS.md).
    - `test-*-*-examples` tests the code found in [/examples](examples).

**Upload to PyPI**

To make a new release onto PyPI, you'll need to have the correct permissions and:

1. Increment version in Qt.py
2. Make a new release here on GitHub, see prior releases for naming-scheme; but in short, it's the version string. No prefix or suffix.
3. The rest is automated, the release ends up on PyPI shortly thereafter


<br>
<br>
<br>

### Qt 6 Transition Guide

| Replace | With | Notes
|:--------|:-----|:----------------------------
| `QFont().fromString(...)` | `QtCompat.QFont.fromString(font, ...)` | Qt6 adds extra data to font strings and changes weight if you want to pass a font string from Qt6 to Qt4/5 use this
| `QFont().setWeight(...)` | `QtCompat.QFont.setWeight(font, ...)`
| `QFont().setWeight(QFont().Bold)` | `QFont().setWeight(QFont.Weight.Bold)` | Instance of class don't have enums, see [see Fully Qualified Enums](CAVEATS.md#fully-qualified-enums)
| `QEvent().Resize` | `QEvent.Type.Resize` | All instances of class don't have enums, see [see Fully Qualified Enums](CAVEATS.md#fully-qualified-enums)
| `QtCore.Qt.MidButton`  | `QtCompat.Qt.MidButton`
| `QLabel.setPixmap(str)` | `QLabel.setPixmap(QPixmap())` | Can't take a string anymore (tested in Maya 2025.0)
| `QModelIndex.child` | `QModel.index` | This one is apparently from Qt 4 and should not have been in Qt.py to begin with
| `QApplication.exec_()` | `QtCompat.QApplication.exec_()` | `exec` is no longer a reserved keyword in python 3 so Qt6 is removing the underscore from `exec_`. Qt.py is using exec_ to preserve compatibility with python 2. The same applies for `QCoreApplication`.
| `QAction().setShortcut(Qt.SHIFT\|Qt.Key_Backspace)` | `QAction().setShortcut(QKeySequence(Qt.Modifier.SHIFT\|Qt.Key.Key_Backspace))` | PyQt6 doesn't accept `QKeyCombination` objects for shortcuts. To work around this cast them to `QKeySequence` objects.
| int(QMainWindow().windowState()) | QtCompat.enumValue(QMainWindow().windowState()) | Consistent interface to convert an enum to an `int`
| `QMouseEvent.globalPos()` | `QtCompat.QMouseEvent.globalPosition(event).toPoint()` | Deprecated in Qt6.0 and removed from PyQt6, currently still in PySide6. Changes from `QPoint` to `QPointF`.
| `QMouseEvent.globalX()` | `QtCompat.QMouseEvent.globalPosition(event).x()` | See `globalPos()`
| `QMouseEvent.globalY()` | `QtCompat.QMouseEvent.globalPosition(event).y()` | See `globalPos()`
| `QMouseEvent.localPos()` | `QtCompat.QMouseEvent.position(event)` | See `globalPos()`
| `QMouseEvent.pos()` | `QtCompat.QMouseEvent.position(event)` | Changes from `QPoint` to `QPointF`. See `globalPos()`
| `QMouseEvent.screenPos()` | `QtCompat.QMouseEvent.globalPosition(event)` | See `globalPos()`
| `QMouseEvent.windowPos()` | `QtCompat.QMouseEvent.scenePosition(event)` | See `globalPos()`
| `QMouseEvent.x()` | `QtCompat.QMouseEvent.position(event).x()` | See `globalPos()`
| `QMouseEvent.y()` | `QtCompat.QMouseEvent.position(event).y()` | See `globalPos()`
| | Submit your known issues here! |

##### Removed Members (Qt.py\==2.\*)

With the removal of support PySide and PyQt4 `Qt.QT_SIP_API_HINT` was removed. `Qt.IsPySide` and `Qt.IsPyQt4` remain for compatibility, but will always return `False` now.

##### Removed Members (Qt.py\==1.4.\*)

Many members were removed from Qt.py due to no longer existing in PySide 6 and PyQt6. They were removed to support Qt 4, 5 and 6.

<details>

<summary>See removed members</summary>

```json
"QtCore": [
    "QAbstractState",
    "QAbstractTransition",
    "QEventTransition",
    "QFinalState",
    "QSignalTransition",
    "QT_TR_NOOP_UTF8",
    "QTextCodec",
    "QTextDecoder",
    "QTextEncoder",
    "QtCriticalMsg",
    "QtDebugMsg",
    "QtFatalMsg",
    "QtSystemMsg",
    "QtWarningMsg",
    "qChecksum",
    "qIsNull",
    "QPictureIO"
],
"QtGui": [
    "qIsGray"
]
"QtMultimedia": [
    "QAbstractVideoBuffer",
    "QAbstractVideoSurface",
    "QAudio",
    "QAudioDeviceInfo",
    "QAudioFormat",
    "QAudioInput",
    "QAudioOutput",
    "QVideoFrame",
    "QVideoSurfaceFormat"
],
"QtNetwork": [
    "QNetworkConfiguration",
    "QNetworkConfigurationManager",
    "QNetworkSession"
],
"QtOpenGL": [
    "QGL",
    "QGLContext",
    "QGLFormat",
    "QGLWidget"
],
"QtSql": [
    "QSql",
    "QSqlDatabase",
    "QSqlDriver",
    "QSqlDriverCreatorBase",
    "QSqlError",
    "QSqlField",
    "QSqlIndex",
    "QSqlQuery",
    "QSqlQueryModel",
    "QSqlRecord",
    "QSqlRelation",
    "QSqlRelationalDelegate",
    "QSqlRelationalTableModel",
    "QSqlResult",
    "QSqlTableModel"
],
"QtWidgets": [
    "QActionGroup",
    "QDesktopWidget",
    "QDirModel",
    "QKeyEventTransition",
    "QMouseEventTransition",
    "QUndoCommand",
    "QUndoGroup",
    "QUndoStack"
],
"QtX11Extras": [
    "QX11Info"
],
"QtXml": [
    "QXmlAttributes",
    "QXmlContentHandler",
    "QXmlDTDHandler",
    "QXmlDeclHandler",
    "QXmlDefaultHandler",
    "QXmlEntityResolver",
    "QXmlErrorHandler",
    "QXmlInputSource",
    "QXmlLexicalHandler",
    "QXmlLocator",
    "QXmlNamespaceSupport",
    "QXmlParseException",
    "QXmlReader",
    "QXmlSimpleReader"
],
"QtXmlPatterns": [
    "QAbstractMessageHandler",
    "QAbstractUriResolver",
    "QAbstractXmlNodeModel",
    "QAbstractXmlReceiver",
    "QSourceLocation",
    "QXmlFormatter",
    "QXmlItem",
    "QXmlName",
    "QXmlNamePool",
    "QXmlNodeModelIndex",
    "QXmlQuery",
    "QXmlResultItems",
    "QXmlSchema",
    "QXmlSchemaValidator",
    "QXmlSerializer"
]
```

</details>

##### Static Members Missing from Instances

An overall change is that instances of classes, like `QFont()` no longer provides access to static members, such as `QFont.Bold`. So things like:

```py
font = QFont()
font.setWeight(font.Bold)
```

Must be replaced with:

```py
font = QFont()
font.setWeight(QFont.Weight.Bold)
```

Or:

This method is not recommended.
```py
font.setWeight(type(font).Weight.Bold)
```

Tedious and seemingly unnecessary.. But there you have it!
> Note: You should also see [Fully Qualified Enums](CAVEATS.md#fully-qualified-enums)

##### Notes

Qt.py 1.4.0, released in May 2024, added support for Qt 6 whilst preserving compatibility with Qt 4 and 5. That means that in most cases, code you've already written for Qt 4 or 5 will now continue to work with Qt 6, such as Maya 2025.

However, some changes between 5 and 6 require up-front work by you the developer to make your codebase run on Qt 6 whilst continuing to run on Qt 4 and 5.

The above is what we know, please do submit issues and pull-request with what else you find!

- https://github.com/mottosso/Qt.py/issues/new

**See also**

The official PySide2 to PySide6 transition guide, which is especially helpful since Qt.py is modeled after PySide2.

- https://doc.qt.io/qtforpython-6/gettingstarted/porting_from2.html