Qt for Python/Considerations

General considerations

QString, QVariant and other types

Qt for Python does not provide access to QString and QVariant, meaning that we decided to use Python's native types for them. Internally we convert Python strings to QStrings and other types that could be accepted as QVariant, like dictionaries, lists and tuples.

Furthermore, the same idea is applied to QChar and QStringRef which are represented as Python strings and QStringList is converted to a Python lists of strings.

QDate, QDateTime, QTime, and QUrl's __hash__() methods return a string representation so that identical dates (and identical date/times or times or URLs) will have identical hash values. QTextStream's bin(), hex(), and oct() functions have been renamed bin_(), hex_(), and oct_(), to avoid conflicting with Python's built-ins of the same names.

QByteArrays, QStrings and Python strings

Previous versions of PySide included a wrong implementation regarding the behavior of QByteArrays, representing them as Python strings. Currently, QByteArray is treated as a list of bytes without an encoding. Please be aware that the equivalent type in Python will depend on its version, Python 2 uses "str" as type, and Python 3 uses "bytes". To avoid confusion, a QString on the other hand, is represented as a human readable string with an encoding, which is represented in Python 2 as an "unicode" object, and in Python 3 as a "str".

The following cases represent the conversion between these types:

Conversion between string and byte types should not be allowed implicitly. So with a Qt API like:

void A::foo(QString a)

The following should happen in Python 3

b = bytes("hi", "utf-8")
c = b"hi" 
d = "hi"
e = str("hi")
A.foo(b) # doesn't work
A.foo(c) # doesn't work
A.foo(d) # works
A.foo(e) # works

And vice versa when expecting a QString, and passing a QByteArray or bytes, the following should happen in Python 3

void A::bar(QByteArray) // or void A::bar(const char *)

b = "hi"
c = str("hi")
d = "hi".encode()
e = QByteArray("hi")
f = b"hi"
A.bar(b) # doesn't work
A.bar(c) # doesn't work
A.bar(d) # works
A.bar(e) # works
A.bar(f) # works

An explicit cast should be used when the user knows what kind of data they have, and what encoding they have / expect, in order to move from QString (Python 3 str, Python 2 unicode) to QByteArray ( Python 3 bytes, Python 2 str) and vice versa.

So if you have a QByteArray, and you know it contains unicode data, and you need to pass it to a function taking a QString, something like this should work in Python 3:

a = QByteArray("hi".encode())
b = bytes(a.data(), "utf-8")
A.foo(b.decode())

And for a function that takes a QByteArray, but you have a Python 2 unicode or Python 3 str, something like this should work:

# On python 3
a = "hi" 
# On python 2
a = unicode("hi")
A.bar(a.encode())

Known issues 5.11

Problems with Python 3.6.0

There seems to be a binary compatibility between 3.6.0 and 3.6.1:

import 'PySide2' # <_frozen_importlib_external.SourceFileLoader object at 0x000001AB2E658F60>
Traceback (most recent call last):
  File "C:\Qt5\pyside-setup\examples\tutorial\t1.py", line 47, in <module>
    from PySide2 import QtWidgets
  File "<frozen importlib._bootstrap>", line 1009, in _handle_fromlist
  File "<frozen importlib._bootstrap>", line 205, in _call_with_frames_removed
  File "<frozen importlib._bootstrap>", line 961, in _find_and_load
  File "<frozen importlib._bootstrap>", line 950, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 648, in _load_unlocked
  File "<frozen importlib._bootstrap>", line 560, in module_from_spec
  File "<frozen importlib._bootstrap_external>", line 922, in create_module
  File "<frozen importlib._bootstrap>", line 205, in _call_with_frames_removed
ImportError: DLL load failed: The specified procedure could not be found.

4628:4698 @ 1025492328 - LdrpReportError - ERROR: Locating export "PyUnicode_AsWideCharString" for DLL "C:\Dev\super_pyside_clang\py360_ap\lib\site-packages\PySide2\QtCore.pyd" failed with status: 0xc0000139

(Related: https://stackoverflow.com/questions/43264773/pil-dll-load-failed-specified-procedure-could-not-be-found/43504007#43504007 )

Missing QtScript

At the moment we do not provide a QtScript interface since most of the functionallity behind it is covered by Python nature, but we plan to include it in the future.

Issues using shiboken2

We have notice that in some linux machines, the built-in shiboken2 does depend of Clang headers that could be not found depending on the Linux distribution. We recommend to have a local PySide2 build when trying to generate bindings for any other c++ project.

Missing WebEngine in Windows 32bit package

This is a current limitation of Qt build itself, because the CI does not build any WebEngine libraries for 32 bit Windows. Thus Qt For Python does not ship WebEngine for 32 bit Windows packages.

Missing DLLs on Windows

Some users have been reporting missing DLLs on the Windows wheels (the wheels for Windows are built using MSVC 2015) a workaround for this issue is to install the C++ Redistributable for Visual Studio 2015.

Documentation

Most of the code snippets on the documentation are based on Qt/C++. It is probable that some pieces are still using C++, so the examples are invalid for Python. We are working to adapt them all, but if you need to understand a certain method or class, you can use our IRC channel to discuss your issue.