Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit c1c4b5a

Browse filesBrowse files
timhoffmtimhoffm
authored
Merge pull request #24423 from anntzer/qtb
Tighten the Qt binding selection docs.
2 parents bf6a70c + b41551d commit c1c4b5a
Copy full SHA for c1c4b5a

File tree

Expand file treeCollapse file tree

7 files changed

+39
-54
lines changed
Filter options
Expand file treeCollapse file tree

7 files changed

+39
-54
lines changed

‎doc/api/backend_gtk3_api.rst

Copy file name to clipboardExpand all lines: doc/api/backend_gtk3_api.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:mod:`.backend_gtk3agg`, :mod:`.backend_gtk3cairo`
22
==================================================
33

4-
**NOTE** These backends are not documented here, to avoid adding a dependency
5-
to building the docs.
4+
**NOTE** These :ref:`backends` are not documented here, to avoid adding a
5+
dependency to building the docs.
66

77
.. redirect-from:: /api/backend_gtk3agg_api
88
.. redirect-from:: /api/backend_gtk3cairo_api

‎doc/api/backend_gtk4_api.rst

Copy file name to clipboardExpand all lines: doc/api/backend_gtk4_api.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:mod:`.backend_gtk4agg`, :mod:`.backend_gtk4cairo`
22
==================================================
33

4-
**NOTE** These backends are not documented here, to avoid adding a dependency
5-
to building the docs.
4+
**NOTE** These :ref:`backends` are not documented here, to avoid adding a
5+
dependency to building the docs.
66

77
.. redirect-from:: /api/backend_gtk4agg_api
88
.. redirect-from:: /api/backend_gtk4cairo_api

‎doc/api/backend_qt_api.rst

Copy file name to clipboardExpand all lines: doc/api/backend_qt_api.rst
+28-28Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:mod:`.backend_qtagg`, :mod:`.backend_qtcairo`
22
==============================================
33

4-
**NOTE** These backends are not (auto) documented here, to avoid adding a
5-
dependency to building the docs.
4+
**NOTE** These :ref:`backends` are not (auto) documented here, to avoid adding
5+
a dependency to building the docs.
66

77
.. redirect-from:: /api/backend_qt4agg_api
88
.. redirect-from:: /api/backend_qt4cairo_api
@@ -26,39 +26,39 @@ supported Python bindings per version -- `PyQt5
2626
<https://www.riverbankcomputing.com/static/Docs/PyQt5/>`_ and `PySide2
2727
<https://doc.qt.io/qtforpython-5/contents.html>`_ for Qt5 and `PyQt6
2828
<https://www.riverbankcomputing.com/static/Docs/PyQt6/>`_ and `PySide6
29-
<https://doc.qt.io/qtforpython/contents.html>`_ for Qt6 [#]_. While both PyQt
29+
<https://doc.qt.io/qtforpython/contents.html>`_ for Qt6 [#]_. Matplotlib's
30+
qtagg and qtcairo backends (``matplotlib.backends.backend_qtagg`` and
31+
``matplotlib.backend.backend_qtcairo``) support all these bindings, with common
32+
parts factored out in the ``matplotlib.backends.backend_qt`` module.
33+
34+
At runtime, these backends select the actual binding used as follows:
35+
36+
1. If a binding's ``QtCore`` subpackage is already imported, that binding is
37+
selected (the order for the check is ``PyQt6``, ``PySide6``, ``PyQt5``,
38+
``PySide2``).
39+
2. If the :envvar:`QT_API` environment variable is set to one of "PyQt6",
40+
"PySide6", "PyQt5", "PySide2" (case-insensitive), that binding is selected.
41+
(See also the documentation on :ref:`environment-variables`.)
42+
3. Otherwise, the first available backend in the order ``PyQt6``, ``PySide6``,
43+
``PyQt5``, ``PySide2`` is selected.
44+
45+
In the past, Matplotlib used to have separate backends for each version of Qt
46+
(e.g. qt4agg/``matplotlib.backends.backend_qt4agg`` and
47+
qt5agg/``matplotlib.backends.backend_qt5agg``). This scheme was dropped when
48+
support for Qt6 was added. For back-compatibility, qt5agg/``backend_qt5agg``
49+
and qt5cairo/``backend_qt5cairo`` remain available; selecting one of these
50+
backends forces the use of a Qt5 binding. Their use is discouraged and
51+
``backend_qtagg`` or ``backend_qtcairo`` should be preferred instead. However,
52+
these modules will not be deprecated until we drop support for Qt5.
53+
54+
While both PyQt
3055
and Qt for Python (aka PySide) closely mirror the underlying C++ API they are
3156
wrapping, they are not drop-in replacements for each other [#]_. To account
3257
for this, Matplotlib has an internal API compatibility layer in
3358
`matplotlib.backends.qt_compat` which covers our needs. Despite being a public
3459
module, we do not consider this to be a stable user-facing API and it may
3560
change without warning [#]_.
3661

37-
Previously Matplotlib's Qt backends had the Qt version number in the name, both
38-
in the module and the :rc:`backend` value
39-
(e.g. ``matplotlib.backends.backend_qt4agg`` and
40-
``matplotlib.backends.backend_qt5agg``). However as part of adding support for
41-
Qt6 we were able to support both Qt5 and Qt6 with a single implementation with
42-
all of the Qt version and binding support handled in
43-
`~matplotlib.backends.qt_compat`. A majority of the renderer agnostic Qt code
44-
is now in `matplotlib.backends.backend_qt` with specialization for AGG in
45-
``backend_qtagg`` and cairo in ``backend_qtcairo``.
46-
47-
The binding is selected at run time based on what bindings are already imported
48-
(by checking for the ``QtCore`` sub-package), then by the :envvar:`QT_API`
49-
environment variable, and finally by the :rc:`backend`. In all cases when we
50-
need to search, the order is ``PyQt6``, ``PySide6``, ``PyQt5``, ``PySide2``.
51-
See :ref:`QT_API-usage` for usage instructions.
52-
53-
The ``backend_qt5``, ``backend_qt5agg``, and ``backend_qt5cairo`` are provided
54-
and force the use of a Qt5 binding for backwards compatibility. Their use is
55-
discouraged (but not deprecated) and ``backend_qt``, ``backend_qtagg``, or
56-
``backend_qtcairo`` should be preferred instead. However, these modules will
57-
not be deprecated until we drop support for Qt5.
58-
59-
60-
61-
6262
.. [#] There is also `PyQt4
6363
<https://www.riverbankcomputing.com/static/Docs/PyQt4/>`_ and `PySide
6464
<https://srinikom.github.io/pyside-docs/>`_ for Qt4 but these are no

‎doc/api/backend_wx_api.rst

Copy file name to clipboardExpand all lines: doc/api/backend_wx_api.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:mod:`.backend_wxagg`, :mod:`.backend_wxcairo`
22
==============================================
33

4-
**NOTE** These backends are not documented here, to avoid adding a dependency
5-
to building the docs.
4+
**NOTE** These :ref:`backends` are not documented here, to avoid adding a
5+
dependency to building the docs.
66

77
.. redirect-from:: /api/backend_wxagg_api
88

‎doc/users/explain/backends.rst

Copy file name to clipboardExpand all lines: doc/users/explain/backends.rst
+3-18Lines changed: 3 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,9 @@ Backend Description
161161
========= ================================================================
162162
QtAgg Agg rendering in a Qt_ canvas (requires PyQt_ or `Qt for Python`_,
163163
a.k.a. PySide). This backend can be activated in IPython with
164-
``%matplotlib qt``.
164+
``%matplotlib qt``. The Qt binding can be selected via the
165+
:envvar:`QT_API` environment variable; see :ref:`QT_bindings` for
166+
more details.
165167
ipympl Agg rendering embedded in a Jupyter widget (requires ipympl_).
166168
This backend can be enabled in a Jupyter notebook with
167169
``%matplotlib ipympl``.
@@ -229,23 +231,6 @@ or
229231
230232
See `installing ipympl <https://matplotlib.org/ipympl/installing.html>`__ for more details.
231233

232-
.. _QT_API-usage:
233-
234-
How do I select the Qt implementation?
235-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
236-
237-
The QtAgg and QtCairo backends support both Qt 5 and 6, as well as both Python
238-
bindings (`PyQt`_ or `Qt for Python`_, a.k.a. PySide). If any binding has
239-
already been loaded, then it will be used for the Qt backend. Otherwise, the
240-
first available binding is used, in the order: PyQt6, PySide6, PyQt5, PySide2.
241-
242-
The :envvar:`QT_API` environment variable can be set to override the search
243-
when nothing has already been loaded. It may be set to (case-insensitively)
244-
PyQt6, PySide6, PyQt5, or PySide2 to pick the version and binding to use. If
245-
the chosen implementation is unavailable, the Qt backend will fail to load
246-
without attempting any other Qt implementations. See :ref:`QT_bindings` for
247-
more details.
248-
249234
Using non-builtin backends
250235
--------------------------
251236
More generally, any importable backend can be selected by using any of the

‎doc/users/faq/environment_variables_faq.rst

Copy file name to clipboardExpand all lines: doc/users/faq/environment_variables_faq.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Environment variables
4848
.. envvar:: QT_API
4949

5050
The Python Qt wrapper to prefer when using Qt-based backends. See :ref:`the
51-
entry in the usage guide <QT_API-usage>` for more information.
51+
entry in the usage guide <QT_bindings>` for more information.
5252

5353
.. _setting-linux-osx-environment-variables:
5454

‎doc/users/prev_whats_new/whats_new_3.5.0.rst

Copy file name to clipboardExpand all lines: doc/users/prev_whats_new/whats_new_3.5.0.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -623,7 +623,7 @@ the Agg or Cairo renderers. Simultaneously, support for Qt4 has been dropped.
623623
Both Qt6 and Qt5 are supported by a combined backend (QtAgg or QtCairo), and
624624
the loaded version is determined by modules already imported, the
625625
:envvar:`QT_API` environment variable, and available packages. See
626-
:ref:`QT_API-usage` for details. The versioned Qt5 backend names (Qt5Agg or
626+
:ref:`QT_bindings` for details. The versioned Qt5 backend names (Qt5Agg or
627627
Qt5Cairo) remain supported for backwards compatibility.
628628

629629
.. _PyQt6: https://www.riverbankcomputing.com/static/Docs/PyQt6/

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.