8000 Tighten the Qt binding selection docs. · matplotlib/matplotlib@b41551d · GitHub
[go: up one dir, main page]
Skip to content

Commit b41551d

Browse files
anntzeranntzer
committed
Tighten the Qt binding selection docs.
- Make the API docs for backend_qtagg/backend_qtcairo the main point documenting QT_API. Reorder the information to first present what's most relevant for end users (1. there are multiple bindings, 2. this is how to select them) before going into the older approach and qt_compat (which is an implementation detail). - Let the backend explanatory docs just refer to the API docs, instead of rewriting essentially the same thing.
1 parent 3d6c3da commit b41551d

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 F438
========= ================================================================
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