Qt.py enables you to write software that runs on any of the 4 supported bindings - PySide2, PyQt5, PySide and PyQt4.
Date | Version | Event |
---|---|---|
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 |
- Project goals
- Install
- Usage
- Documentation
- Rules
- How it works
- Known problems
- Who's using Qt.py?
- Projects using Qt.py
- Projects similar to Qt.py
- Developer guide
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 - PySide, PySide2, PyQt4 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
for more details.
Qt.py is a single file and can either be copy/pasted into your project, downloaded as-is, cloned as-is or installed via pip
or conda
.
# From PyPI
$ pip install Qt.py
# 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. 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
Use Qt.py as you would use PySide2.
import sys
from Qt import QtWidgets
app = QtWidgets.QApplication(sys.argv)
button = QtWidgets.QPushButton("Hello World")
button.show()
app.exec_()
- Also see /examples
All members of Qt
stem directly from those available via PySide2, 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
>>> from Qt import __binding__
>>> __binding__
'PyQt5'
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 PyQt4.loadUi and PySide equivalent |
translate(...) |
function |
Compatibility wrapper around QCoreApplication.translate |
wrapInstance(addr=long, type=QObject) |
QObject |
Wrapper around shiboken2.wrapInstance and PyQt equivalent |
getCppPointer(object=QObject) |
long |
Wrapper around shiboken2.getCppPointer and PyQt equivalent |
Example
>>> from Qt import QtCompat
>>> QtCompat.loadUi
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.
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.
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 | str | Override order and content of binding to try. |
QT_VERBOSE | bool | Be a little more chatty about what's going on with Qt.py |
QT_SIP_API_HINT | int | Sets the preferred SIP api version that will be attempted to set. |
Members of Qt.py is a subset of PySide2. Which means for a member to be made accessible via Qt.py, it will need to (1) be accessible via PySide2 and (2) each of the other supported bindings. This excludes large portions of the Qt framework, including the newly added QtQml and QtQuick modules but guarantees that anything you develop with Qt.py will work identically on any binding - PySide, PySide2, PyQt4 and PyQt5. If you need to use such excluded modules with Qt.py, please see QtSiteConfig.py.
We call this subset "common members" and these can be generated by running the build_membership.sh
script. The script will output all modules and members of each binding into individual JSON files. These JSON files are then compared and a common_members.json
file is generated. The contents of this file is copy-pasted into the _common_members
dictionary of Qt.py. Please note that the script will only use the very latest version of our Docker test suite to generate the common members subset, using the most up-to-date set of VFX Platform-stipulated software versions.
Some bindings offer features not available in others, you can use __binding__
to capture those.
if "PySide" in __binding__:
do_pyside_stuff()
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.
$ 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.
# Try PyQt first and then PySide, but nothing else.
$ export QT_PREFERRED_BINDING=PyQt:PySide
Using the OS path separator (os.pathsep
) which is :
on Unix systems and ;
on Windows.
Add or remove members from Qt.py at run-time.
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.
- Create a new file
QtSiteConfig.py
- Implement
update_members
- Expose to 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.
$ set PYTHONPATH=/path/to
$ python -c "import Qt.QtCore"
ImportError: No module named Qt.QtCore
Linux and MacOS users, replace
set
withexport
WARNING - ALPHA FUNCTIONALITY
See #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.
$ 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
The uic.loadUi
function of PyQt4 and PyQt5 as well as the QtUiTools.QUiLoader().load
function of PySide/PySide2 are mapped to a convenience function loadUi
.
import sys
from Qt import QtCompat
app = QtWidgets.QApplication(sys.argv)
ui = QtCompat.loadUi(uifile="my.ui")
ui.show()
app.exec_()
For PyQt
bindings it uses their native implementation, whereas for PySide
bindings it uses our custom implementation borrowed from the qtpy project.
loadUi
has two arguments as opposed to the multiple that PyQt ships with. See here 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.
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.
If you're using PyQt4, sip
attempts to set its API to version 2 for the following:
QString
QVariant
QDate
QDateTime
QTextStream
QTime
QUrl
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 5 documentation is always right. Where the documentation lacks answers, PySide2 is right.
For example.
# PyQt5 adheres to PySide2 signals and slots
PyQt5.Signal = PyQt5.pyqtSignal
PyQt5.Slot = PyQt5.pyqtSlot
# PySide2 adheres to the official documentation
PySide2.QtCore.QStringListModel = PySide2.QtGui.QStringListModel
Caveats
There are cases where Qt.py is not handling incompatibility issues. Please see CAVEATS.md
for more information.
Send us a pull-request with known problems here!
Send us a pull-request with your studio here.
- Atomic Fiction
- Industrial Brothers
- Moonbot Studios
- Sony Pictures Imageworks
- Colorbleed
- Method Studios
- Framestore
- Weta Digital
- Disney Animation
- Industriromantik
- Psyop
- ftrack
- Fido
- Bläck
- CGRU
- MPC
- Rising Sun Pictures
- Blur Studio
- Mikros Image
- Mackevision
Presented at Siggraph 2016, BOF!
Send us a pull-request with your project here.
- Cosmos
- maya-capture-gui
- pyblish-lite
- pyvfx-boilerplate
- riffle
- cmt
- PythonForMayaSamples
- Kraken
- AFANASY
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 |
Also worth mentioning, pyqt4topyqt5; a good starting point for transitioning to Qt.py.
Send us a pull-request with your project here.
Tests are performed on each aspect of the shim.
Each of these are run under..
- Python 2.7
- Python 3.4
- Python 3.5
- Python 3.6
..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.
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.
if binding("PyQt4"):
def test_something_related_to_pyqt4():
pass
Code convention
Below are some of the conventions that used throughout the Qt.py module and tests.
- Etiquette: PEP8
- All code is written in PEP8. It is recommended you use a linter as you work, flake8 and pylinter are both good options. Anaconda if using Sublime is another good option.
- Etiquette: Double quotes
- " = yes, ' = no.
- Etiquette: Napoleon docstrings
- Any docstrings are made in Google Napoleon format. See Napoleon for details.
- Etiquette: Semantic Versioning
- This project follows semantic versioning.
- 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 Docker.
With Docker setup, here's what you do. Please note this will pull down a ~1 GB image.
cd Qt.py
# Run nosetests (Linux/OSX)
docker run --rm -v $(pwd):/Qt.py -e PYTHON=2.7 fredrikaverpil/qt.py:2018
docker run --rm -v $(pwd):/Qt.py -e PYTHON=3.4 fredrikaverpil/qt.py:2018
docker run --rm -v $(pwd):/Qt.py -e PYTHON=3.5 fredrikaverpil/qt.py:2018
docker run --rm -v $(pwd):/Qt.py -e PYTHON=3.6 fredrikaverpil/qt.py:2018
# Run nosetests (Windows)
docker run --rm -v %CD%:/Qt.py -e PYTHON=2.7 fredrikaverpil/qt.py:2018
docker run --rm -v %CD%:/Qt.py -e PYTHON=3.4 fredrikaverpil/qt.py:2018
docker run --rm -v %CD%:/Qt.py -e PYTHON=3.5 fredrikaverpil/qt.py:2018
docker run --rm -v %CD%:/Qt.py -e PYTHON=3.6 fredrikaverpil/qt.py:2018
# Doctest: test_caveats.test_1_qtgui_qabstractitemmodel_createindex ... ok
# Doctest: test_caveats.test_2_qtgui_qabstractitemmodel_createindex ... ok
# Doctest: test_caveats.test_3_qtcore_qitemselection ... ok
# ...
#
# ----------------------------------------------------------------------
# Ran 21 tests in 7.799s
#
# OK
Now both you and Travis are operating on the same assumptions which means that when the tests pass on your machine, they pass on Travis. And everybody wins!
For details on the Docker image for testing, see DOCKER.md
.
See CONTRIBUTING.md
for more of the good stuff.