1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
******************************************************************************
``matplotlib.backends.backend_qtagg``, ``matplotlib.backends.backend_qtcairo``
******************************************************************************
**NOTE** These :ref:`backends` are not (auto) documented here, to avoid adding
a dependency to building the docs.
.. redirect-from:: /api/backend_qt4agg_api
.. redirect-from:: /api/backend_qt4cairo_api
.. redirect-from:: /api/backend_qt5agg_api
.. redirect-from:: /api/backend_qt5cairo_api
.. module:: matplotlib.backends.qt_compat
.. module:: matplotlib.backends.backend_qt
.. module:: matplotlib.backends.backend_qtagg
.. module:: matplotlib.backends.backend_qtcairo
.. module:: matplotlib.backends.backend_qt5agg
.. module:: matplotlib.backends.backend_qt5cairo
.. _QT_bindings:
Qt Bindings
-----------
There are currently 2 actively supported Qt versions, Qt5 and Qt6, and two
supported Python bindings per version -- `PyQt5
<https://www.riverbankcomputing.com/static/Docs/PyQt5/>`_ and `PySide2
<https://doc.qt.io/qtforpython-5/contents.html>`_ for Qt5 and `PyQt6
<https://www.riverbankcomputing.com/static/Docs/PyQt6/>`_ and `PySide6
<https://doc.qt.io/qtforpython/contents.html>`_ for Qt6 [#]_. Matplotlib's
qtagg and qtcairo backends (``matplotlib.backends.backend_qtagg`` and
``matplotlib.backend.backend_qtcairo``) support all these bindings, with common
parts factored out in the ``matplotlib.backends.backend_qt`` module.
At runtime, these backends select the actual binding used as follows:
1. If a binding's ``QtCore`` subpackage is already imported, that binding is
selected (the order for the check is ``PyQt6``, ``PySide6``, ``PyQt5``,
``PySide2``).
2. If the :envvar:`QT_API` environment variable is set to one of "PyQt6",
"PySide6", "PyQt5", "PySide2" (case-insensitive), that binding is selected.
(See also the documentation on :ref:`environment-variables`.)
3. Otherwise, the first available backend in the order ``PyQt6``, ``PySide6``,
``PyQt5``, ``PySide2`` is selected.
In the past, Matplotlib used to have separate backends for each version of Qt
(e.g. qt4agg/``matplotlib.backends.backend_qt4agg`` and
qt5agg/``matplotlib.backends.backend_qt5agg``). This scheme was dropped when
support for Qt6 was added. For back-compatibility, qt5agg/``backend_qt5agg``
and qt5cairo/``backend_qt5cairo`` remain available; selecting one of these
backends forces the use of a Qt5 binding. Their use is discouraged and
``backend_qtagg`` or ``backend_qtcairo`` should be preferred instead. However,
these modules will not be deprecated until we drop support for Qt5.
While both PyQt
and Qt for Python (aka PySide) closely mirror the underlying C++ API they are
wrapping, they are not drop-in replacements for each other [#]_. To account
for this, Matplotlib has an internal API compatibility layer in
`matplotlib.backends.qt_compat` which covers our needs. Despite being a public
module, we do not consider this to be a stable user-facing API and it may
change without warning [#]_.
.. [#] There is also `PyQt4
<https://www.riverbankcomputing.com/static/Docs/PyQt4/>`_ and `PySide
<https://srinikom.github.io/pyside-docs/>`_ for Qt4 but these are no
longer supported by Matplotlib and upstream support for Qt4 ended
in 2015.
.. [#] Despite the slight API differences, the more important distinction
between the PyQt and Qt for Python series of bindings is licensing.
.. [#] If you are looking for a general purpose compatibility library please
see `qtpy <https://github.com/spyder-ide/qtpy>`_.
|
