10000 Merge pull request #24423 from anntzer/qtb · matplotlib/matplotlib@c1c4b5a · GitHub
[go: up one dir, main page]
Skip to content

Commit c1c4b5a

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

File tree

7 files changed

+39
-54
lines changed

7 files changed

+39
-54
lines changed

‎doc/api/backend_gtk3_api.rst

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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