8000 DOC: Add links to explicit vs implicit API everywhere "OO" is used · tacaswell/matplotlib@512a006 · GitHub
[go: up one dir, main page]
Skip to content

Commit 512a006

Browse files
tacaswelltacaswell
committed
DOC: Add links to explicit vs implicit API everywhere "OO" is used
Closes matplotlib#18249
1 parent 921e9ac commit 512a006

File tree

11 files changed

+95
-72
lines changed

11 files changed

+95
-72
lines changed

‎doc/api/index.rst

Lines changed: 26 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -114,10 +114,33 @@ Alphabetical list of modules:
114114
Usage patterns
115115
--------------
116116

117-
Below we describe several common approaches to plotting with Matplotlib.
117+
Below we describe several common approaches to plotting with Matplotlib. See
118+
:ref:`api_interfaces` for an explanation of the trade off of the supported user
119+
APIs.
118120

119-
The pyplot API
120-
^^^^^^^^^^^^^^
121+
122+
The Explicit API
123+
^^^^^^^^^^^^^^^^
124+
125+
At its core, Matplotlib is an object-oriented library. We recommend directly
126+
working with the objects, if you need more control and customization of your
127+
plots.
128+
129+
In many cases you will create a `.Figure` and one or more
130+
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
131+
on these objects. However, it's also possible to create `.Figure`\ s
132+
explicitly (e.g. when including them in GUI applications).
133+
134+
Further reading:
135+
136+
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
137+
plotting functions.
138+
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
139+
(except for the pyplot section)
140+
141+
142+
The implicit API
143+
^^^^^^^^^^^^^^^^
121144

122145
`matplotlib.pyplot` is a collection of functions that make
123146
Matplotlib work like MATLAB. Each pyplot function makes some change to a
@@ -135,24 +158,6 @@ Further reading:
135158

136159
.. _api-index:
137160

138-
The object-oriented API
139-
^^^^^^^^^^^^^^^^^^^^^^^
140-
141-
At its core, Matplotlib is object-oriented. We recommend directly working
142-
with the objects, if you need more control and customization of your plots.
143-
144-
In many cases you will create a `.Figure` and one or more
145-
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
146-
on these objects. However, it's also possible to create `.Figure`\ s
147-
explicitly (e.g. when including them in GUI applications).
148-
149-
Further reading:
150-
151-
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
152-
plotting functions.
153-
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
154-
(except for the pyplot section)
155-
156161
The pylab API (discouraged)
157162
^^^^^^^^^^^^^^^^^^^^^^^^^^^
158163

‎doc/users/project/history.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ History
1111
Matplotlib is a library for making 2D plots of arrays in `Python
1212
<https://www.python.org>`_. Although it has its origins in emulating
1313
the MATLAB graphics commands, it is
14-
independent of MATLAB, and can be used in a Pythonic, object oriented
14+
independent of MATLAB, and can be used in a Pythonic, object-oriented
1515
way. Although Matplotlib is written primarily in pure Python, it
1616
makes heavy use of `NumPy <https://numpy.org>`_ and other extension
1717
code to provide good performance even for large arrays.

‎examples/misc/pythonic_matplotlib.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
Pythonic Matplotlib
44
===================
55
6-
Some people prefer to write more pythonic, object-oriented code
7-
rather than use the pyplot interface to matplotlib. This example shows
8-
you how.
6+
Some people prefer to write more "Pythonic", explicitly object-oriented code
7+
rather than use the implicit pyplot interface to Matplotlib. This example
8+
shows you how.
99
1010
Unless you are an application developer, I recommend using part of the
1111
pyplot interface, particularly the figure, close, subplot, axes, and
@@ -14,7 +14,7 @@
1414
instances, managing the bounding boxes of the figure elements,
1515
creating and realizing GUI windows and embedding figures in them.
1616
17-
If you are an application developer and want to embed matplotlib in
17+
If you are an application developer and want to embed Matplotlib in
1818
your application, follow the lead of examples/embedding_in_wx.py,
1919
examples/embedding_in_gtk.py or examples/embedding_in_tk.py. In this
2020
case you will want to control the creation of all your figures,
@@ -28,7 +28,7 @@
2828
application developers, however.
2929
3030
If you see an example in the examples dir written in pyplot interface,
31-
and you want to emulate that using the true python method calls, there
31+
and you want to emulate that using the true Python method calls, there
3232
is an easy mapping. Many of those examples use 'set' to control
3333
figure properties. Here's how to map those commands onto instance
3434
methods
@@ -52,6 +52,7 @@
5252
a.set_yticklabels([])
5353
a.set_xticks([])
5454
a.set_yticks([])
55+
5556
"""
5657

5758
import matplotlib.pyplot as plt

‎examples/subplots_axes_and_figures/multiple_figs_demo.py

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@
1010
1111
.. note::
1212
13-
We discourage working with multiple figures in pyplot because managing
14-
the *current figure* is cumbersome and error-prone. Instead, we recommend
15-
to use the object-oriented approach and call methods on Figure and Axes
16-
instances.
13+
We discourage working with multiple figures in implicit pyplot interface
14+
because managing the *current figure* is cumbersome and
15+
error-prone. Instead, we recommend to use the explicit approach and call
16+
methods on Figure and Axes instances. See :ref:`api_interfaces` for an
17+
explanation of the tradeoffs between the implicit and explicit interfaces.
1718
1819
"""
1920
import matplotlib.pyplot as plt

‎lib/matplotlib/__init__.py

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,12 @@
1717
1818
at the ipython shell prompt.
1919
20-
For the most part, direct use of the object-oriented library is encouraged when
21-
programming; pyplot is primarily for working interactively. The exceptions are
22-
the pyplot functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`,
23-
and `.pyplot.savefig`, which can greatly simplify scripting.
20+
For the most part, direct use of the explicit object-oriented library is
21+
encouraged when programming; the implicit pyplot interface is primarily for
22+
working interactively. The exceptions are the pyplot functions
23+
`.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and `.pyplot.savefig`,
24+
which can greatly simplify scripting. See :ref:`api_interfaces` for an
25+
explanation of the tradeoffs between the implicit and explicit interfaces.
2426
2527
Modules include:
2628
@@ -79,6 +81,7 @@
7981
8082
Occasionally the internal documentation (python docstrings) will refer
8183
to MATLAB&reg;, a registered trademark of The MathWorks, Inc.
84+
8285
"""
8386

8487
import atexit

‎lib/matplotlib/pyplot.py

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
y = np.sin(x)
1717
plt.plot(x, y)
1818
19-
The explicit (object-oriented) API is recommended for complex plots, though
19+
The explicit object-oriented API is recommended for complex plots, though
2020
pyplot is still usually used to create the figure and often the axes in the
2121
figure. See `.pyplot.figure`, `.pyplot.subplots`, and
2222
`.pyplot.subplot_mosaic` to create figures, and
@@ -29,6 +29,10 @@
2929
y = np.sin(x)
3030
fig, ax = plt.subplots()
3131
ax.plot(x, y)
32+
33+
34+
See :ref:`api_interfaces` for an explanation of the tradeoffs between the
35+
implicit and explicit interfaces.
3236
"""
3337

3438
import functools

‎tutorials/introductory/images.py

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,15 @@
3737
cells below those that create the plot will change the plot - it is a
3838
live object in memory.
3939
40-
This tutorial will use Matplotlib's imperative-style plotting
41-
interface, pyplot. This interface maintains global state, and is very
42-
useful for quickly and easily experimenting with various plot
43-
settings. The alternative is the object-oriented interface, which is also
44-
very powerful, and generally more suitable for large application
45-
development. If you'd like to learn about the object-oriented
46-
interface, a great place to start is our :doc:`Quick start guide
47-
</tutorials/introductory/quick_start>`. For now, let's get on
48-
with the imperative-style approach:
40+
This tutorial will use Matplotlib's implicit plotting interface, pyplot. This
41+
interface maintains global state, and is very useful for quickly and easily
42+
experimenting with various plot settings. The alternative is the explicit,
43+
which is more suitable for large application development. For an explanation
44+
of the tradeoffs between the implicit and explicit interfaces See
45+
:ref:`api_interfaces` and the :doc:`Quick start guide
46+
</tutorials/introductory/quick_start>` to start using the explicit interface.
47+
For now, let's get on with the implicit approach:
48+
4949
"""
5050

5151
import matplotlib.pyplot as plt

‎tutorials/introductory/lifecycle.py

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,17 @@
1717
<https://pbpython.com/effective-matplotlib.html>`_
1818
by Chris Moffitt. It was transformed into this tutorial by Chris Holdgraf.
1919
20-
A note on the Object-Oriented API vs. Pyplot
21-
============================================
20+
A note on the explicit vs. implicit interfaces
21+
==============================================
2222
23-
Matplotlib has two interfaces. The first is an object-oriented (OO)
24-
interface. In this case, we utilize an instance of :class:`axes.Axes`
25-
in order to render visualizations on an instance of :class:`figure.Figure`.
23+
Matplotlib has two interfaces. For an explanation of the tradeoffs between the
24+
implicit and explicit interfaces see :ref:`api_interfaces`.
2625
27-
The second is based on MATLAB and uses a state-based interface. This is
28-
encapsulated in the :mod:`.pyplot` module. See the :doc:`pyplot tutorials
26+
The first is an explicit object-oriented (OO) interface. In this case, we
27+
utilize an instance of :class:`axes.Axes` in order to render visualizations on
28+
an instance of :class:`figure.Figure`. The second is based on MATLAB and uses
29+
an implicit global state-based interface. This is encapsulated in the
30+
:mod:`.pyplot` module. See the :doc:`pyplot tutorials
2931
</tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
3032
interface.
3133
@@ -41,14 +43,15 @@
4143
4244
.. note::
4345
44-
In general, try to use the object-oriented interface over the pyplot
45-
interface.
46+
In general, try to use the explicit interface over the implicit pyplot
47+
interface for plotting.
4648
4749
Our data
4850
========
4951
5052
We'll use the data from the post from which this tutorial was derived.
5153
It contains sales information for a number of companies.
54+
5255
"""
5356

5457
# sphinx_gallery_thumbnail_number = 10

‎tutorials/introductory/pyplot.py

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,20 @@
44
===============
55
66
An introduction to the pyplot interface. Please also see
7-
:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib works.
7+
:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib
8+
works and :ref:`api_interfaces` for an explanation of the trade off of the
9+
supported user APIs.
10+
811
"""
912

1013
###############################################################################
1114
# Intro to pyplot
1215
# ===============
1316
#
14-
# :mod:`matplotlib.pyplot` is a collection of functions
15-
# that make matplotlib work like MATLAB.
16-
# Each ``pyplot`` function makes
17-
# some change to a figure: e.g., creates a figure, creates a plotting area
18-
# in a figure, plots some lines in a plotting area, decorates the plot
19-
# with labels, etc.
17+
# :mod:`matplotlib.pyplot` is a collection of functions that make matplotlib
18+
# work like MATLAB. Each ``pyplot`` function makes some change to a figure:
19+
# e.g., creates a figure, creates a plotting area in a figure, plots some lines
20+
# in a plotting area, decorates the plot with labels, etc.
2021
#
2122
# In :mod:`matplotlib.pyplot` various states are preserved
2223
# across function calls, so that it keeps track of things like
@@ -28,10 +29,11 @@
2829
#
2930
# .. note::
3031
#
31-
# the pyplot API is generally less-flexible than the object-oriented API.
32-
# Most of the function calls you see here can also be called as methods
33-
# from an ``Axes`` object. We recommend browsing the tutorials and
34-
# examples to see how this works.
32+
# the implicit pyplot API is generally terser but less-flexible than the
33+
# explicit API. Most of the function calls you see here can also be called
34+
# as methods from an ``Axes`` object. We recommend browsing the tutorials
35+
# and examples to see how this works. See :ref:`api_interfaces` for an
36+
# explanation of the trade off of the supported user APIs.
3537
#
3638
# Generating visualizations with pyplot is very quick:
3739

@@ -301,7 +303,7 @@ def f(t):
301303
# and the current axes with `~.pyplot.cla`. If you find
302304
# it annoying that states (specifically the current image, figure and axes)
303305
# are being maintained for you behind the scenes, don't despair: this is just a thin
304-
# stateful wrapper around an object oriented API, which you can use
306+
# stateful wrapper around an object-oriented API, which you can use
305307
# instead (see :doc:`/tutorials/intermediate/artists`)
306308
#
307309
# If you are making lots of figures, you need to be aware of one

‎tutorials/introductory/quick_start.py

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,16 +134,19 @@
134134
# Coding styles
135135
# =============
136136
#
137-
# The object-oriented and the pyplot interfaces
138-
# ---------------------------------------------
137+
# The explicit and the implicit interfaces
138+
# ----------------------------------------
139139
#
140140
# As noted above, there are essentially two ways to use Matplotlib:
141141
#
142142
# - Explicitly create Figures and Axes, and call methods on them (the
143143
# "object-oriented (OO) style").
144-
# - Rely on pyplot to automatically create and manage the Figures and Axes, and
144+
# - Rely on pyplot to implicitly create and manage the Figures and Axes, and
145145
# use pyplot functions for plotting.
146146
#
147+
# See :ref:`api_interfaces` for an explanation of the tradeoffs between the
148+
# implicit and explicit interfaces.
149+
#
147150
# So one can use the OO-style
148151

149152
x = np.linspace(0, 2, 100) # Sample data.

0 commit comments

Comments
 (0)
0