matplotlib · greglucas · Apr 8, 2022 · Mar 6, 2022 · Mar 7, 2022 · Mar 7, 2022
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -30,6 +30,62 @@ methods on them to plot data, add axis labels and a figure title.
    fig.set_facecolor('lightsteelblue')
 
 
+
+.. _usage_patterns:
+
+Usage patterns
+--------------
+
+Below we describe several common approaches to plotting with Matplotlib.  See
+:ref:`api_interfaces` for an explanation of the trade-offs between the supported user
+APIs.
+
+
+The explicit API
+^^^^^^^^^^^^^^^^
+
+At its core, Matplotlib is an object-oriented library. We recommend directly
+working with the objects if you need more control and customization of your
+plots.
+
+In many cases you will create a `.Figure` and one or more
+`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
+on these objects. However, it's also possible to create `.Figure`\ s
+explicitly (e.g. when including them in GUI applications).
+
+Further reading:
+
+- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
+  plotting functions.
+- Most of the :ref:`examples <examples-index>` use the object-oriented approach
+  (except for the pyplot section)
+
+
+The implicit API
+^^^^^^^^^^^^^^^^
+
+`matplotlib.pyplot` is a collection of functions that make
+Matplotlib work like MATLAB. Each pyplot function makes some change to a
+figure: e.g., creates a figure, creates a plotting area in a figure, plots
+some lines in a plotting area, decorates the plot with labels, etc.
+
+`.pyplot` is mainly intended for interactive plots and simple cases of
+programmatic plot generation.
+
+Further reading:
+
+- The `matplotlib.pyplot` function reference
+- :doc:`/tutorials/introductory/pyplot`
+- :ref:`Pyplot examples <pyplots_examples>`
+
+.. _api-index:
+
+The pylab API (discouraged)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: pylab
+   :no-members:
+
 Modules
 -------
 
@@ -107,54 +163,3 @@ Alphabetical list of modules:
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst
    toolkits/axes_grid.rst
-
-
-.. _usage_patterns:
-
-Usage patterns
---------------
-
-Below we describe several common approaches to plotting with Matplotlib.
-
-The pyplot API
-^^^^^^^^^^^^^^
-
-`matplotlib.pyplot` is a collection of functions that make
-Matplotlib work like MATLAB. Each pyplot function makes some change to a
-figure: e.g., creates a figure, creates a plotting area in a figure, plots
-some lines in a plotting area, decorates the plot with labels, etc.
-
-`.pyplot` is mainly intended for interactive plots and simple cases of
-programmatic plot generation.
-
-Further reading:
-
-- The `matplotlib.pyplot` function reference
-- :doc:`/tutorials/introductory/pyplot`
-- :ref:`Pyplot examples <pyplots_examples>`
-
-.. _api-index:
-
-The object-oriented API
-^^^^^^^^^^^^^^^^^^^^^^^
-
-At its core, Matplotlib is object-oriented. We recommend directly working
-with the objects, if you need more control and customization of your plots.
-
-In many cases you will create a `.Figure` and one or more
-`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
-on these objects. However, it's also possible to create `.Figure`\ s
-explicitly (e.g. when including them in GUI applications).
-
-Further reading:
-
-- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
-   plotting functions.
-- Most of the :ref:`examples <examples-index>` use the object-oriented approach
-   (except for the pyplot section)
-
-The pylab API (discouraged)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: pylab
-   :no-members:
diff --git a/doc/users/project/history.rst b/doc/users/project/history.rst
@@ -11,7 +11,7 @@ History
 Matplotlib is a library for making 2D plots of arrays in `Python
 <https://www.python.org>`_.  Although it has its origins in emulating
 the MATLAB graphics commands, it is
-independent of MATLAB, and can be used in a Pythonic, object oriented
+independent of MATLAB, and can be used in a Pythonic, object-oriented
 way.  Although Matplotlib is written primarily in pure Python, it
 makes heavy use of `NumPy <https://numpy.org>`_ and other extension
 code to provide good performance even for large arrays.

diff --git a/examples/misc/pythonic_matplotlib.py b/examples/misc/pythonic_matplotlib.py
@@ -3,9 +3,9 @@
 Pythonic Matplotlib
 ===================
 
-Some people prefer to write more pythonic, object-oriented code
-rather than use the pyplot interface to matplotlib.  This example shows
-you how.
+Some people prefer to write more "Pythonic", explicit object-oriented code,
+rather than use the implicit pyplot interface to Matplotlib. This example
+shows you how to take advantage of the explicit Matplotlib interface.
 
 Unless you are an application developer, I recommend using part of the
 pyplot interface, particularly the figure, close, subplot, axes, and
@@ -14,7 +14,7 @@
 instances, managing the bounding boxes of the figure elements,
 creating and realizing GUI windows and embedding figures in them.
 
-If you are an application developer and want to embed matplotlib in
+If you are an application developer and want to embed Matplotlib in
 your application, follow the lead of examples/embedding_in_wx.py,
 examples/embedding_in_gtk.py or examples/embedding_in_tk.py.  In this
 case you will want to control the creation of all your figures,
@@ -28,7 +28,7 @@
 application developers, however.
 
 If you see an example in the examples dir written in pyplot interface,
-and you want to emulate that using the true python method calls, there
+and you want to emulate that using the true Python method calls, there
 is an easy mapping.  Many of those examples use 'set' to control
 figure properties.  Here's how to map those commands onto instance
 methods
@@ -52,6 +52,7 @@
     a.set_yticklabels([])
     a.set_xticks([])
     a.set_yticks([])
+
 """
 
 import matplotlib.pyplot as plt

diff --git a/examples/subplots_axes_and_figures/multiple_figs_demo.py b/examples/subplots_axes_and_figures/multiple_figs_demo.py
@@ -10,10 +10,11 @@
 
 .. note::
 
-    We discourage working with multiple figures in pyplot because managing
-    the *current figure* is cumbersome and error-prone. Instead, we recommend
-    to use the object-oriented approach and call methods on Figure and Axes
-    instances.
+    We discourage working with multiple figures through the implicit pyplot
+    interface because managing the *current figure* is cumbersome and
+    error-prone. Instead, we recommend using the explicit approach and call
+    methods on Figure and Axes instances. See :ref:`api_interfaces` for an
+    explanation of the trade-offs between the implicit and explicit interfaces.
 
 """
 import matplotlib.pyplot as plt

diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -17,10 +17,13 @@
 
 at the ipython shell prompt.
 
-For the most part, direct use of the object-oriented library is encouraged when
-programming; pyplot is primarily for working interactively.  The exceptions are
-the pyplot functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`,
-and `.pyplot.savefig`, which can greatly simplify scripting.
+For the most part, direct use of the explicit object-oriented library is
+encouraged when programming; the implicit pyplot interface is primarily for
+working interactively. The exceptions to this suggestion are the pyplot
+functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and
+`.pyplot.savefig`, which can greatly simplify scripting.  See
+:ref:`api_interfaces` for an explanation of the tradeoffs between the implicit
+and explicit interfaces.
 
 Modules include:
 
@@ -79,6 +82,7 @@
 
 Occasionally the internal documentation (python docstrings) will refer
 to MATLAB&reg;, a registered trademark of The MathWorks, Inc.
+
 """
 
 import atexit

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -16,7 +16,7 @@
     y = np.sin(x)
     plt.plot(x, y)
 
-The explicit (object-oriented) API is recommended for complex plots, though
+The explicit object-oriented API is recommended for complex plots, though
 pyplot is still usually used to create the figure and often the axes in the
 figure. See `.pyplot.figure`, `.pyplot.subplots`, and
 `.pyplot.subplot_mosaic` to create figures, and
@@ -29,6 +29,10 @@
     y = np.sin(x)
     fig, ax = plt.subplots()
     ax.plot(x, y)
+
+
+See :ref:`api_interfaces` for an explanation of the tradeoffs between the
+implicit and explicit interfaces.
 """
 
 import functools

diff --git a/tutorials/introductory/images.py b/tutorials/introductory/images.py
@@ -37,15 +37,15 @@
 cells below those that create the plot will change the plot - it is a
 live object in memory.
 
-This tutorial will use Matplotlib's imperative-style plotting
-interface, pyplot.  This interface maintains global state, and is very
-useful for quickly and easily experimenting with various plot
-settings.  The alternative is the object-oriented interface, which is also
-very powerful, and generally more suitable for large application
-development.  If you'd like to learn about the object-oriented
-interface, a great place to start is our :doc:`Quick start guide
-</tutorials/introductory/quick_start>`.  For now, let's get on
-with the imperative-style approach:
+This tutorial will use Matplotlib's implicit plotting interface, pyplot.  This
+interface maintains global state, and is very useful for quickly and easily
+experimenting with various plot settings.  The alternative is the explicit,
-experimenting with various plot settings.  The alternative is the explicit,
+experimenting with various plot settings. The alternative is the explicit,
-experimenting with various plot settings.  The alternative is the explicit,
+experimenting with various plot settings. The alternative is the explicit,
+which is more suitable for large application development.  For an explanation
-which is more suitable for large application development.  For an explanation
+which is more suitable for large application development. For an explanation
-which is more suitable for large application development.  For an explanation
+which is more suitable for large application development. For an explanation
+of the tradeoffs between the implicit and explicit interfaces See
-of the tradeoffs between the implicit and explicit interfaces See
+of the tradeoffs between the implicit and explicit interfaces, see
-of the tradeoffs between the implicit and explicit interfaces See
+of the tradeoffs between the implicit and explicit interfaces, see
+:ref:`api_interfaces` and the :doc:`Quick start guide
+</tutorials/introductory/quick_start>` to start using the explicit interface.
+For now, let's get on with the implicit approach:
+
 """
 
 import matplotlib.pyplot as plt

diff --git a/tutorials/introductory/lifecycle.py b/tutorials/introductory/lifecycle.py
@@ -17,17 +17,19 @@
     <https://pbpython.com/effective-matplotlib.html>`_
     by Chris Moffitt. It was transformed into this tutorial by Chris Holdgraf.
 
-A note on the Object-Oriented API vs. Pyplot
-============================================
+A note on the explicit vs. implicit interfaces
+==============================================
 
-Matplotlib has two interfaces. The first is an object-oriented (OO)
-interface. In this case, we utilize an instance of :class:`axes.Axes`
-in order to render visualizations on an instance of :class:`figure.Figure`.
+Matplotlib has two interfaces. For an explanation of the trade-offs between the
+explicit and implicit interfaces see :ref:`api_interfaces`.
 
-The second is based on MATLAB and uses a state-based interface. This is
-encapsulated in the :mod:`.pyplot` module. See the :doc:`pyplot tutorials
-</tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
-interface.
+In the explicit object-oriented (OO) interface we directly utilize instances of
+:class:`axes.Axes` to build up the visualization in an instance of
+:class:`figure.Figure`.  In the implicit interface, inspired by and modeled on
+MATLAB, uses an global state-based interface which is is encapsulated in the
+:mod:`.pyplot` module to plot to the "current Axes".  See the :doc:`pyplot
+tutorials </tutorials/introductory/pyplot>` for a more in-depth look at the
+pyplot interface.
 
 Most of the terms are straightforward but the main thing to remember
 is that:
@@ -41,14 +43,15 @@
 
 .. note::
 
-   In general, try to use the object-oriented interface over the pyplot
-   interface.
+   In general prefer the explicit interface over the implicit pyplot interface
+   for plotting.
 
 Our data
 ========
 
 We'll use the data from the post from which this tutorial was derived.
 It contains sales information for a number of companies.
+
 """
 
 # sphinx_gallery_thumbnail_number = 10

diff --git a/tutorials/introductory/pyplot.py b/tutorials/introductory/pyplot.py
@@ -4,19 +4,20 @@
 ===============
 
 An introduction to the pyplot interface.  Please also see
-:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib works.
+:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib
+works and :ref:`api_interfaces` for an explanation of the trade-offs between the
+supported user APIs.
+
 """
 
 ###############################################################################
 # Intro to pyplot
 # ===============
 #
-# :mod:`matplotlib.pyplot` is a collection of functions
-# that make matplotlib work like MATLAB.
-# Each ``pyplot`` function makes
-# some change to a figure: e.g., creates a figure, creates a plotting area
-# in a figure, plots some lines in a plotting area, decorates the plot
-# with labels, etc.
+# :mod:`matplotlib.pyplot` is a collection of functions that make matplotlib
+# work like MATLAB.  Each ``pyplot`` function makes some change to a figure:
-# work like MATLAB.  Each ``pyplot`` function makes some change to a figure:
+# work like MATLAB. Each ``pyplot`` function makes some change to a figure:
-# work like MATLAB.  Each ``pyplot`` function makes some change to a figure:
+# work like MATLAB. Each ``pyplot`` function makes some change to a figure:
+# e.g., creates a figure, creates a plotting area in a figure, plots some lines
+# in a plotting area, decorates the plot with labels, etc.
 #
 # In :mod:`matplotlib.pyplot` various states are preserved
 # across function calls, so that it keeps track of things like
@@ -28,10 +29,11 @@
 #
 # .. note::
 #
-#    the pyplot API is generally less-flexible than the object-oriented API.
-#    Most of the function calls you see here can also be called as methods
-#    from an ``Axes`` object. We recommend browsing the tutorials and
-#    examples to see how this works.
+#    the implicit pyplot API is generally less verbose but also not as flexible as the
+#    explicit API.  Most of the function calls you see here can also be called
-#    explicit API.  Most of the function calls you see here can also be called
+#    explicit API. Most of the function calls you see here can also be called
-#    explicit API.  Most of the function calls you see here can also be called
+#    explicit API. Most of the function calls you see here can also be called
+#    as methods from an ``Axes`` object. We recommend browsing the tutorials
+#    and examples to see how this works. See :ref:`api_interfaces` for an
+#    explanation of the trade off of the supported user APIs.
 #
 # Generating visualizations with pyplot is very quick:
 
@@ -301,7 +303,7 @@ def f(t):
 # and the current axes with `~.pyplot.cla`.  If you find
 # it annoying that states (specifically the current image, figure and axes)
 # are being maintained for you behind the scenes, don't despair: this is just a thin
-# stateful wrapper around an object oriented API, which you can use
+# stateful wrapper around an object-oriented API, which you can use
 # instead (see :doc:`/tutorials/intermediate/artists`)
 #
 # If you are making lots of figures, you need to be aware of one

diff --git a/tutorials/introductory/quick_start.py b/tutorials/introductory/quick_start.py
@@ -134,16 +134,19 @@
 # Coding styles
 # =============
 #
-# The object-oriented and the pyplot interfaces
-# ---------------------------------------------
+# The explicit and the implicit interfaces
+# ----------------------------------------
 #
 # As noted above, there are essentially two ways to use Matplotlib:
 #
 # - Explicitly create Figures and Axes, and call methods on them (the
 #   "object-oriented (OO) style").
-# - Rely on pyplot to automatically create and manage the Figures and Axes, and
+# - Rely on pyplot to implicitly create and manage the Figures and Axes, and
 #   use pyplot functions for plotting.
 #
+# See :ref:`api_interfaces` for an explanation of the tradeoffs between the
+# implicit and explicit interfaces.
+#
 # So one can use the OO-style
 
 x = np.linspace(0, 2, 100)  # Sample data.

diff --git a/tutorials/text/text_intro.py b/tutorials/text/text_intro.py
@@ -31,11 +31,11 @@
 Basic text commands
 ===================
 
-The following commands are used to create text in the pyplot
-interface and the object-oriented API:
+The following commands are used to create text in the implicit and explicit
+interfaces (see :ref:`api_interfaces` for an explanation of the tradeoffs):
 
 =================== =================== ======================================
-`.pyplot` API       OO API              description
+implicit API        explicit API        description
 =================== =================== ======================================
 `~.pyplot.text`     `~.Axes.text`       Add text at an arbitrary location of
                                         the `~matplotlib.axes.Axes`.
@@ -63,6 +63,7 @@
 configured with a variety of font and other properties.  The example below
 shows all of these commands in action, and more detail is provided in the
 sections that follow.
+
 """
 
 import matplotlib