From 9429b0f2ea634c3c3d3202d1264082672b40b23a Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 2 Nov 2023 05:24:49 -0400 Subject: [PATCH] Backport PR #26669: [DOC] debug backends --- doc/users/faq.rst | 8 ++ galleries/users_explain/figure/backends.rst | 106 ++++++++++++++++-- .../users_explain/figure/figure_intro.rst | 6 +- .../users_explain/figure/interactive.rst | 2 +- galleries/users_explain/quick_start.py | 4 +- lib/matplotlib/figure.py | 2 +- 6 files changed, 112 insertions(+), 16 deletions(-) diff --git a/doc/users/faq.rst b/doc/users/faq.rst index c4e133d56d73..970016ed19e6 100644 --- a/doc/users/faq.rst +++ b/doc/users/faq.rst @@ -8,6 +8,13 @@ Frequently Asked Questions ========================== +.. _how-do-no-figure: + +I don't see a figure window +--------------------------- + +Please see :ref:`figures-not-showing`. + .. _how-to-too-many-ticks: Why do I have so many ticks, and/or why are they out of order? @@ -301,6 +308,7 @@ you must in that case use a *non-interactive backend* (typically Agg), because most GUI backends *require* being run from the main thread as well. .. _reporting-problems: +.. _get-help: Get help -------- diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst index b769fcc12ba2..41345d46d6ff 100644 --- a/galleries/users_explain/figure/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -11,17 +11,17 @@ Backends What is a backend? ------------------ -A lot of documentation on the website and in the mailing lists refers -to the "backend" and many new users are confused by this term. -Matplotlib targets many different use cases and output formats. Some -people use Matplotlib interactively from the Python shell and have -plotting windows pop up when they type commands. Some people run -`Jupyter `_ notebooks and draw inline plots for -quick data analysis. Others embed Matplotlib into graphical user -interfaces like PyQt or PyGObject to build rich applications. Some -people use Matplotlib in batch scripts to generate postscript images -from numerical simulations, and still others run web application -servers to dynamically serve up graphs. +Backends are used for displaying Matplotlib figures (see :ref:`figure-intro`), +on the screen, or for writing to files. A lot of documentation on the website +and in the mailing lists refers to the "backend" and many new users are +confused by this term. Matplotlib targets many different use cases and output +formats. Some people use Matplotlib interactively from the Python shell and +have plotting windows pop up when they type commands. Some people run `Jupyter +`_ notebooks and draw inline plots for quick data +analysis. Others embed Matplotlib into graphical user interfaces like PyQt or +PyGObject to build rich applications. Some people use Matplotlib in batch +scripts to generate postscript images from numerical simulations, and still +others run web application servers to dynamically serve up graphs. To support all of these use cases, Matplotlib can target different outputs, and each of these capabilities is called a backend; the @@ -248,3 +248,87 @@ backend, use ``module://name.of.the.backend`` as the backend name, e.g. ``matplotlib.use('module://name.of.the.backend')``. Information for backend implementers is available at :ref:`writing_backend_interface`. + +.. _figures-not-showing: + +Debugging the figure windows not showing +---------------------------------------- + +Sometimes things do not work as expected, usually during an install. + +If you are using a Notebook or integrated development environment (see :ref:`notebooks-and-ides`), +please consult their documentation for debugging figures not working in their +environments. + +If you are using one of Matplotlib's graphics backends (see :ref:`standalone-scripts-and-interactive-use`), make sure you know which +one is being used: + +.. code-block:: python3 + + import matplotlib + + print(matplotlib.get_backend()) + +Try a simple plot to see if the GUI opens: + +.. code-block:: python3 + + import matplotlib + import matplotlib.pyplot as plt + + print(matplotlib.get_backend()) + plt.plot((1, 4, 6)) + plt.show() + +If it does not, you perhaps have an installation problem. A good step at this +point is to ensure that your GUI toolkit is installed properly, taking +Matplotlib out of the testing. Almost all GUI toolkits have a small test +program that can be run to test basic functionality. If this test fails, try re-installing. + +QtAgg, QtCairo, Qt5Agg, and Qt5Cairo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Test ``PyQt5``. + +If you have ``PySide`` or ``PyQt6`` installed rather than ``PyQt5``, just change the import +accordingly: + +.. code-block:: bash + + python -c "from PyQt5.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()" + + +TkAgg and TkCairo +^^^^^^^^^^^^^^^^^ + +Test ``tkinter``: + +.. code-block:: bash + + python3 -c "from tkinter import Tk; Tk().mainloop()" + +GTK3Agg, GTK4Agg, GTK3Cairo, GTK4Cairo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Test ``Gtk``: + +.. code-block:: bash + + python3 -c "from gi.repository import Gtk; win = Gtk.Window(); win.connect('destroy', Gtk.main_quit); win.show(); Gtk.main()" + +wxAgg and wxCairo +^^^^^^^^^^^^^^^^^ + +Test ``wx``: + +.. code-block:: python3 + + import wx + + app = wx.App(False) # Create a new app, don't redirect stdout/stderr to a window. + frame = wx.Frame(None, wx.ID_ANY, "Hello World") # A Frame is a top-level window. + frame.Show(True) # Show the frame. + app.MainLoop() + +If the test works for your desired backend but you still cannot get Matplotlib to display a figure, then contact us (see +:ref:`get-help`). diff --git a/galleries/users_explain/figure/figure_intro.rst b/galleries/users_explain/figure/figure_intro.rst index ac7286c119e8..978e2b87fe98 100644 --- a/galleries/users_explain/figure/figure_intro.rst +++ b/galleries/users_explain/figure/figure_intro.rst @@ -1,7 +1,7 @@ .. redirect-from:: /users/explain/figure -.. _figure_explanation: +.. _figure-intro: +++++++++++++++++++++++ Introduction to Figures @@ -36,6 +36,8 @@ We will discuss how to create Figures in more detail below, but first it is helpful to understand how to view a Figure. This varies based on how you are using Matplotlib, and what :ref:`Backend ` you are using. +.. _notebooks-and-ides: + Notebooks and IDEs ------------------ @@ -82,6 +84,8 @@ other than the default "inline" backend, you will likely need to use an ipython %matplotlib notebook +.. _standalone-scripts-and-interactive-use: + Standalone scripts and interactive use -------------------------------------- diff --git a/galleries/users_explain/figure/interactive.rst b/galleries/users_explain/figure/interactive.rst index 9a4c4956ed6d..6fd908fcac7a 100644 --- a/galleries/users_explain/figure/interactive.rst +++ b/galleries/users_explain/figure/interactive.rst @@ -15,7 +15,7 @@ mouse-location tools built into the Matplotlib GUI windows are often sufficient, you can also use the event system to build customized data exploration tools. .. seealso:: - :ref:`figure_explanation`. + :ref:`figure-intro`. Matplotlib ships with :ref:`backends ` binding to diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index c8b6a072d6f5..7cdd2b0b3208 100644 --- a/galleries/users_explain/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -38,7 +38,7 @@ # # Note that to get this Figure to display, you may have to call ``plt.show()``, # depending on your backend. For more details of Figures and backends, see -# :ref:`figure_explanation`. +# :ref:`figure-intro`. # # .. _figure_parts: # @@ -71,7 +71,7 @@ # :ref:`Matplotlib backends ` support zooming and # panning on figure windows. # -# For more on Figures, see :ref:`figure_explanation`. +# For more on Figures, see :ref:`figure-intro`. # # :class:`~matplotlib.axes.Axes` # ------------------------------ diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 9a75811fe13f..b2d75bcdd736 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -27,7 +27,7 @@ Some situations call for directly instantiating a `~.figure.Figure` class, usually inside an application of some sort (see :ref:`user_interfaces` for a list of examples) . More information about Figures can be found at -:ref:`figure_explanation`. +:ref:`figure-intro`. """ from contextlib import ExitStack