Qt for Python/GettingStarted

Considerations before starting

PySide2 supports Python 2 (recommended: 2.7 onwards, Compatibility module six installed) and Python 3 (recommended: 3.5 onwards).

On Windows, it is recommended to use Python 3 and build with MSVC2015. Python 2 requires building with MSVC2008.

Currently, only Qt 5.6 is supported. Qt needs to be build with the QtXmlPatterns module.

Development

Development happens in the dev branches of the repositories. The top level repository has several submodules:

• sources/shiboken2: Shiboken Parser
• sources/pyside2: PySide 2
• sources/pyside2-examples: Examples
• sources/pyside2-tools: uic, rcc
• wiki: Wiki

Contributions follow the standard process.

Building requires CMake.

It is helpful to have debug binaries and/or symbols for Python available. On Windows, this is done choosing Customized Installation when installing python and ticking the respective check boxes. On Linux, debug packages can be installed in addition. For Ubuntu, the packages python3-dbg, libpython3-dbg provide a debug binary python3-dbg.

It is also recommended to use a Virtual Environment for testing to be able to always start from a clean base and avoid issues with write permissions in installations.

On Linux, the command

virtualenv -p /usr/bin/python3-dbg testenv

creates a Virtual Environment named testenv for debugging purposes. On Windows, an installation step may be required:

python -m pip install virtualenv
python -m virtualenv testenv

The Virtual Environment is activated by

 source testenv/bin/activate

or

CALL testenv\Scripts\activate.bat

Before building the first time, the module Sphinx should be installed into the virtual environment:

pip install sphinx

Building PySide2

PySide2 is ideally built from a source-based package provided for your platform's package manager (e.g., Arch Linux's pacman, Gentoo Linux's Portage). If your platform fails to provide such a package, PySide2 may also be manually built from scratch as a fallback.

Arch Linux

Arch Linux automates PySide2 installation from source via the AUR package pyside2-git as follows:

• Download pyside2-git.

git clone aur.archlinux/pyside2-git.git

• Install pyside2-git.

cd pyside2-git
makepkg -srci

Gentoo Linux

Gentoo Linux automates PySide2 installation from source via the pyside-9999:2 package hosted by the official qt overlay as follows:

• Install layman (if you haven't already).

emerge layman
echo 'source /var/lib/layman/make.conf' >> /etc/portage/make.conf

• Add the qt overlay.

layman -a qt

• Synchronize overlays.

layman -S

• Unmask pyside-9999:2 and shiboken-9999:2.

echo '~dev-python/pyside-9999:2 **\n~dev-python/shiboken-9999:2 **' >> /etc/portage/package.accept_keywords

• (Optional) Enable pyside-9999:2 USE flags. Most USE flags currently supported by the official PyQt5 ebuild are also supported by the pyside-9999:2 ebuild. For example:

echo '~dev-python/pyside-9999:2 concurrent designer help testlib widgets -kde -phonon -script -sql -webkit -webchannel -webengine' >> /etc/portage/package.use

• Install pyside-9999:2 and shiboken-9999:2.

emerge pyside-9999:2

Manually

The script setup.py in the top level repository is used to build and install the PySide2 package. It takes a mode argument (build or install) and several options.

Various options:

• --qmake=<binary> Path to qmake of the Qt library to be used
• --cmake=<binary> Path to cmake
• --build-tests: Creates a directory containing the tests along with some helper packages
• --ignore-git: Prevents setup.py from cloning and checking out the submodules.
• --debug: Build in Debug mode
• --reuse-build: Rebuilds only modified files (currently does not work for typesystem xml files)
• --openssl: Path to OpenSSL

A typical invocation looks like:

setup.py install --build-tests

A successful build can be tested by running an example:

 python sources/pyside2-examples/examples/widgets/tetrix.py

Note: When local builds of Qt on Linux, the environment LD_LIBRARY_PATH needs to be set to point to the location of the Qt library when running examples, as otherwise they are not found by Python.

Manually on Ubuntu (Debug Build)

This is useful for debugging into the interpreter as well as into extensions. Roughly the steps are the following:

git clone https://github.com/python/cpython python3.6 && cd python3.6 && git checkout 3.6
sudo apt-get build-dep python3.5 # (at time of writing 3.6 was not packaged yet, but it doesn't matter, it's just build dependencies)
mkdir build_debug && cd build_debug
../configure --with-pydebug --enable-shared --prefix=/home/CHANGE_ME/python36_installed LDFLAGS="-Wl,--rpath=/home/CHANGE_ME/python36_installed/lib" # (you can modify the install path to any directory you wish, make sure to change it in the rpath setting as well)
make -j4 && make install
virtualenv -p /home/CHANGE_ME/python36_installed/bin/python3.6dm py36

After that you can build PySide2 using the custom Python interpreter, using the virtualenv you created in the last step. Make sure to change the paths to reflect your own directory structure.

cd /path/to/location/of/pyside/supermodule
python setup.py install --qmake=/home/CHANGE_ME/qt56/bin/qmake --cmake=/usr/bin/cmake --openssl=/usr/bin/openssl --debug --jobs=4 --ignore-git --build-tests

Running Tests

Go to the build directory:

cd ~/pyside-setup/testenv_build/py3.5-qt5.6.3-64bit-release/pyside2/tests/QtGui

Run all tests in the module:

make test

Run only one test(qpainter_test):

ctest -R qpainter_test --verbose

Building the Documentation

This is currently unexplored terrain PYSIDE-363.

• The sources are in pyside2/doc
• libXML2 and libXSLT should be present when building PySide2 (Ubuntu: apt-get install libxml2-dev libxslt1-dev)
• graphviz + dot should be installed
• QT_SRC_DIR needs to be set
• sphinx should be installed (pip install sphinx)
• qdoc3 is used to generate it

Using Qt Creator as a project explorer

Qt Creator 4.0+ can be used to open the PySide and Shiboken CMakeLists.txt files as projects, and thus provide usual IDE features for developing PySide - project file navigation, code completion (C++ only), following symbols under cursor (C++ only), syntax highlighting, locator usage, debugging, etc.

Currently there is a limitation that Shiboken has to be built first using the terminal, because the installed shiboken CMake packages will have to be specified for the PySide project in Qt Creator.

The steps for opening the projects in Qt Creator are:

1. Open pyside-setup/sources/shiboken2/CMakeLists.txt, and specify a 5.6 Qt Kit to be used
2. Build the project as usual (by pressing the build icon for instance)
3. Open pyside-setup/sources/pyside2/CMakeLists.txt, and specify the same 5.6 Qt Kit
4. Go to projects tab, and under the Build / CMake section find the Shiboken2_DIR setting. You have to specify the path to the folder where the Shiboken CMake package was installed when you compiled Shiboken from the terminal
5. An example path under MacOS is /Users/user/Dev/pyside2-setup/pyside_install/py2.7-qt5.6.1-64bit-debug/lib/cmake/Shiboken2-2.0.0. The path has to be adjusted depending on the user folder name, the version of python and qt, etc
6. (Optional) On MacOS you also have to set the ALTERNATIVE_QT_INCLUDE_DIR setting to the Qt kit include path (e.g. /Users/user/Dev/qt56_source/include)
7. Apply the CMake configuration changes (by pressing the button), and you should be able to build PySide

Now you can use the project explorer to look through the source cpp files, python files, use the locator feature to open files and file classes / methods, and other features that Qt Creator provides.