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'sbin(), 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:

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:

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 noticed that on some linux machines, the built-in shiboken2 depends on Clang headers that are 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 Windows / Python 2.7 release

The official Python 2.7 binary package which can be downloaded at https://www.python.org/downloads/ is built using MSVC 2008. The Qt libraries are built using MSVC 2015/2017.

Both of these will load different MSVC runtime libraries, which is unsafe.

The usual recommendation is that all built software should use the same MSVC runtime libraries, otherwise this could lead to memory corruption, crashes or undefined behavior.

Note that if you build your own custom Python2.7 interpreter with an MSVC version equivalent to the one that Qt was built with, you can safely build and use Qt For Python against that Python interpreter.

ImportError: DLL load failed: The specified module could not be found

If you try to use the PySide2 package on Windows within a virtual environment and you see an error similar to the one below, make sure to update your virtualenv package to the latest version (16.1.0+) and then recreate the virtual environment.

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.