##// END OF EJS Templates
Update Matplotlib docs
Ian Thomas -
Show More
@@ -14,7 +14,7 b' from IPython.utils.decorators import flag_calls'
14
14
15
15
16 # Matplotlib backend resolution functionality moved from IPython to Matplotlib
16 # Matplotlib backend resolution functionality moved from IPython to Matplotlib
17 # in IPython 8.24 and Matplotlib 3.9.1. Need to keep `backends` and `backend2gui`
17 # in IPython 8.24 and Matplotlib 3.9.0. Need to keep `backends` and `backend2gui`
18 # here for earlier Matplotlib and for external backend libraries such as
18 # here for earlier Matplotlib and for external backend libraries such as
19 # mplcairo that might rely upon it.
19 # mplcairo that might rely upon it.
20 _deprecated_backends = {
20 _deprecated_backends = {
@@ -485,6 +485,10 b' def _matplotlib_manages_backends() -> bool:'
485 matplotlib.backends.registry.backend_registry is available along with
485 matplotlib.backends.registry.backend_registry is available along with
486 member functions resolve_gui_or_backend, resolve_backend, list_all, and
486 member functions resolve_gui_or_backend, resolve_backend, list_all, and
487 list_gui_frameworks.
487 list_gui_frameworks.
488
489 This function can be removed as it will always return True when Python
490 3.12, the latest version supported by Matplotlib < 3.9, reaches
491 end-of-life in late 2028.
488 """
492 """
489 global _matplotlib_manages_backends_value
493 global _matplotlib_manages_backends_value
490 if _matplotlib_manages_backends_value is None:
494 if _matplotlib_manages_backends_value is None:
@@ -82,12 +82,14 b' shell_flags[\'nosep\']=(nosep_config, "Eliminate all spacing between prompts.")'
82 shell_flags['pylab'] = (
82 shell_flags['pylab'] = (
83 {'InteractiveShellApp' : {'pylab' : 'auto'}},
83 {'InteractiveShellApp' : {'pylab' : 'auto'}},
84 """Pre-load matplotlib and numpy for interactive use with
84 """Pre-load matplotlib and numpy for interactive use with
85 the default matplotlib backend."""
85 the default matplotlib backend. The exact options available
86 depend on what Matplotlib provides at runtime.""",
86 )
87 )
87 shell_flags['matplotlib'] = (
88 shell_flags['matplotlib'] = (
88 {'InteractiveShellApp' : {'matplotlib' : 'auto'}},
89 {'InteractiveShellApp' : {'matplotlib' : 'auto'}},
89 """Configure matplotlib for interactive use with
90 """Configure matplotlib for interactive use with
90 the default matplotlib backend."""
91 the default matplotlib backend. The exact options available
92 depend on what Matplotlib provides at runtime.""",
91 )
93 )
92
94
93 # it's possible we don't want short aliases for *all* of these:
95 # it's possible we don't want short aliases for *all* of these:
@@ -114,7 +116,7 b" shell_aliases['cache-size'] = 'InteractiveShell.cache_size'"
114 class MatplotlibBackendCaselessStrEnum(CaselessStrEnum):
116 class MatplotlibBackendCaselessStrEnum(CaselessStrEnum):
115 """An enum of Matplotlib backend strings where the case should be ignored.
117 """An enum of Matplotlib backend strings where the case should be ignored.
116
118
117 Prior to Matplotlib 3.9.1 the list of valid backends is hardcoded in
119 Prior to Matplotlib 3.9.0 the list of valid backends is hardcoded in
118 pylabtools.backends. After that, Matplotlib manages backends.
120 pylabtools.backends. After that, Matplotlib manages backends.
119
121
120 The list of valid backends is determined when it is first needed to avoid
122 The list of valid backends is determined when it is first needed to avoid
@@ -205,12 +207,14 b' class InteractiveShellApp(Configurable):'
205 matplotlib = MatplotlibBackendCaselessStrEnum(
207 matplotlib = MatplotlibBackendCaselessStrEnum(
206 allow_none=True,
208 allow_none=True,
207 help="""Configure matplotlib for interactive use with
209 help="""Configure matplotlib for interactive use with
208 the default matplotlib backend.""",
210 the default matplotlib backend. The exact options available
211 depend on what Matplotlib provides at runtime.""",
209 ).tag(config=True)
212 ).tag(config=True)
210 pylab = MatplotlibBackendCaselessStrEnum(
213 pylab = MatplotlibBackendCaselessStrEnum(
211 allow_none=True,
214 allow_none=True,
212 help="""Pre-load matplotlib and numpy for interactive use,
215 help="""Pre-load matplotlib and numpy for interactive use,
213 selecting a particular matplotlib backend and loop integration.
216 selecting a particular matplotlib backend and loop integration.
217 The exact options available depend on what Matplotlib provides at runtime.
214 """,
218 """,
215 ).tag(config=True)
219 ).tag(config=True)
216 pylab_import_all = Bool(
220 pylab_import_all = Bool(
@@ -16,6 +16,8 b' difference as object are most of the time represented by text, but in notebook'
16 and similar interface you will get richer outputs.
16 and similar interface you will get richer outputs.
17
17
18
18
19 .. _matplotlib_magic:
20
19 Plotting
21 Plotting
20 --------
22 --------
21
23
@@ -32,36 +34,48 b' are the output of running code cells. The IPython kernel is designed to work'
32 seamlessly with the matplotlib_ plotting library to provide this functionality.
34 seamlessly with the matplotlib_ plotting library to provide this functionality.
33
35
34 To set this up, before any plotting or import of matplotlib is performed you
36 To set this up, before any plotting or import of matplotlib is performed you
35 must execute the ``%matplotlib`` :ref:`magic command <magics_explained>`. This
37 may execute the ``%matplotlib`` :ref:`magic command <magics_explained>`. This
36 performs the necessary behind-the-scenes setup for IPython to work correctly
38 performs the necessary behind-the-scenes setup for IPython to work correctly
37 hand in hand with ``matplotlib``; it does *not*, however, actually execute any
39 hand in hand with ``matplotlib``; it does *not*, however, actually execute any
38 Python ``import`` commands, that is, no names are added to the namespace.
40 Python ``import`` commands, that is, no names are added to the namespace.
39
41
40 If the ``%matplotlib`` magic is called without an argument, the
42 If you do not use the ``%matplotlib`` magic or you call it without an argument,
41 output of a plotting command is displayed using the default ``matplotlib``
43 the output of a plotting command is displayed using the default ``matplotlib``
42 backend in a separate window. Alternatively, the backend can be explicitly
44 backend, which may be different depending on Operating System and whether
43 requested using, for example::
45 running within Jupyter or not.
46
47 Alternatively, the backend can be explicitly requested using, for example::
44
48
45 %matplotlib gtk
49 %matplotlib gtk
46
50
47 A particularly interesting backend, provided by IPython, is the ``inline``
51 The argument passed to the ``%matplotlib`` magic command may be the name of any
48 backend. This is available only for the Jupyter Notebook and the
52 backend understood by ``matplotlib`` or it may the name of a GUI loop such as
49 Jupyter QtConsole. It can be invoked as follows::
53 ``qt`` or ``osx``, in which case an appropriate backend supporting that GUI
54 loop will be selected. To obtain a full list of all backends and GUI loops
55 understood by ``matplotlib`` use ``%matplotlib --list``.
50
56
51 %matplotlib inline
57 There are some specific backends that are used in the Jupyter ecosystem:
52
58
53 With this backend, the output of plotting commands is displayed *inline* within
59 - The ``inline`` backend is provided by IPython and can be used in Jupyter Lab,
54 frontends like the Jupyter notebook, directly below the code cell that produced
60 Notebook and QtConsole; it is the default backend when using Jupyter. The
55 it. The resulting plots will then also be stored in the notebook document.
61 outputs of plotting commands are displayed *inline* within frontends like
62 Jupyter Notebook, directly below the code cells that produced them.
63 The resulting plots will then also be stored in the notebook document.
56
64
57 .. seealso::
65 - The ``notebook`` or ``nbagg`` backend is built into ``matplotlib`` and can be
66 used with Jupyter ``notebook <7`` and ``nbclassic``. Plots are interactive so
67 they can be zoomed and panned.
58
68
59 `Plotting with Matplotlib`_ example notebook
69 - The ``ipympl`` or ``widget`` backend is for use with Jupyter ``lab`` and
70 ``notebook >=7``. It is in a separate ``ipympl`` module that must be
71 installed using ``pip`` or ``conda`` in the usual manner. Plots are
72 interactive so they can be zoomed and panned.
60
73
74 .. seealso::
61
75
62 The matplotlib_ library also ships with ``%matplotlib notebook`` command that
76 `Plotting with Matplotlib`_ example notebook
63 allows interactive figures if your environment allows it.
64
77
65 See the matplotlib_ documentation for more information.
78 See the matplotlib_ documentation for more information, in particular the
79 section on backends.
66
80
67 .. include:: ../links.txt
81 .. include:: ../links.txt
@@ -44,7 +44,7 b' the command-line by passing the full class name and a corresponding value; type'
44 <...snip...>
44 <...snip...>
45 --matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib)
45 --matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib)
46 Default: None
46 Default: None
47 Choices: ['auto', 'gtk', 'gtk3', 'gtk4', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt5', 'qt6', 'tk', 'wx']
47 Choices: ['auto', 'gtk3', 'gtk4', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt5', 'qt6', 'tk', 'wx']
48 Configure matplotlib for interactive use with the default matplotlib
48 Configure matplotlib for interactive use with the default matplotlib
49 backend.
49 backend.
50 <...snip...>
50 <...snip...>
@@ -902,7 +902,7 b' For users, enabling GUI event loop integration is simple. You simple use the'
902 %gui [GUINAME]
902 %gui [GUINAME]
903
903
904 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
904 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
905 arguments include ``wx``, ``qt``, ``qt5``, ``qt6``, ``gtk``, ``gtk3`` ``gtk4``, and
905 arguments include ``wx``, ``qt``, ``qt5``, ``qt6``, ``gtk3`` ``gtk4``, and
906 ``tk``.
906 ``tk``.
907
907
908 Thus, to use wxPython interactively and create a running :class:`wx.App`
908 Thus, to use wxPython interactively and create a running :class:`wx.App`
@@ -937,29 +937,12 b' PyQt and PySide'
937
937
938 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
938 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
939 PyQt or PySide. ``qt`` implies "use the latest version available", and it favors
939 PyQt or PySide. ``qt`` implies "use the latest version available", and it favors
940 PyQt over PySide. To request a specific version, use ``qt5`` or ``qt6``. Note that
940 PyQt over PySide. To request a specific version, use ``qt5`` or ``qt6``.
941 Qt4 is not supported with the ``--gui`` switch (and has not been for some time now).
942
941
943 If specified, IPython will respect the environment variable ``QT_API`` used
942 If specified, IPython will respect the environment variable ``QT_API``. If
944 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
943 ``QT_API`` is not specified and you launch IPython in matplotlib mode with
945 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
944 ``ipython --matplotlib=qt`` then IPython will ask matplotlib which Qt library
946 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
945 to use. See the matplotlib_ documentation on ``QT_API`` for further details.
947 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
948
949 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
950 then IPython will ask matplotlib which Qt library to use (only if QT_API is
951 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
952 older, then IPython will always use PyQt4 without setting the v2 APIs, since
953 neither v2 PyQt nor PySide work.
954
955 .. warning::
956
957 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
958 to work with IPython's qt integration, because otherwise PyQt4 will be
959 loaded in an incompatible mode.
960
961 It also means that you must *not* have ``QT_API`` set if you want to
962 use ``--gui=qt`` with code that requires PyQt4 API v1.
963
946
964
947
965 .. _matplotlib_support:
948 .. _matplotlib_support:
@@ -969,19 +952,16 b' Plotting with matplotlib'
969
952
970 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
953 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
971 can produce plots on screen using a variety of GUI toolkits, including Tk,
954 can produce plots on screen using a variety of GUI toolkits, including Tk,
972 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
955 PyGTK, PyQt6 and wxPython. It also provides a number of commands useful for
973 scientific computing, all with a syntax compatible with that of the popular
956 scientific computing, all with a syntax compatible with that of the popular
974 Matlab program.
957 Matlab program.
975
958
976 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
959 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
977 IPython is already running, you can run the :magic:`matplotlib` magic. If no
960 IPython is already running, you can run the :magic:`matplotlib` magic. If no
978 arguments are given, IPython will automatically detect your choice of
961 arguments are given, IPython will automatically detect your choice of
979 matplotlib backend. You can also request a specific backend with
962 matplotlib backend. For information on matplotlib backends see
980 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
963 :ref:`matplotlib_magic`.
981 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
964
982 backend value, which produces static figures inlined inside the application
983 window instead of matplotlib's interactive figures that live in separate
984 windows.
985
965
986 .. _interactive_demos:
966 .. _interactive_demos:
987
967
1 NO CONTENT: modified file
NO CONTENT: modified file
General Comments 0
You need to be logged in to leave comments. Login now