8000 Merge pull request #22613 from tacaswell/doc_oo_to_explicit · matplotlib/matplotlib@a436253 · GitHub
[go: up one dir, main page]
Skip to content

Commit a436253

Browse files
greglucasgreglucas
authored
Merge pull request #22613 from tacaswell/doc_oo_to_explicit
DOC: Add links to explicit vs implicit API everywhere "OO" is used
2 parents 0e46ff2 + 7083aba commit a436253

File tree

11 files changed

+128
-104
lines changed

11 files changed

+128
-104
lines changed

‎doc/api/index.rst‎

Lines changed: 56 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,62 @@ methods on them to plot data, add axis labels and a figure title.
3030
fig.set_facecolor('lightsteelblue')
3131

3232

33+
34+
.. _usage_patterns:
35+
36+
Usage patterns
37+
--------------
38+
39+
Below we describe several common approaches to plotting with Matplotlib. See
40+
:ref:`api_interfaces` for an explanation of the trade-offs between the supported user
41+
APIs.
42+
43+
44+
The explicit API
45+
^^^^^^^^^^^^^^^^
46+
47+
At its core, Matplotlib is an object-oriented library. We recommend directly
48+
working with the objects if you need more control and customization of your
49+
plots.
50+
51+
In many cases you will create a `.Figure` and one or more
52+
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
53+
on these objects. However, it's also possible to create `.Figure`\ s
54+
explicitly (e.g. when including them in GUI applications).
55+
56+
Further reading:
57+
58+
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
59+
plotting functions.
60+
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
61+
(except for the pyplot section)
62+
63+
64+
The implicit API
65+
^^^^^^^^^^^^^^^^
66+
67+
`matplotlib.pyplot` is a collection of functions that make
68+
Matplotlib work like MATLAB. Each pyplot function makes some change to a
69+
figure: e.g., creates a figure, creates a plotting area in a figure, plots
70+
some lines in a plotting area, decorates the plot with labels, etc.
71+
72+
`.pyplot` is mainly intended for interactive plots and simple cases of
73+
programmatic plot generation.
74+
75+
Further reading:
76+
77+
- The `matplotlib.pyplot` function reference
78+
- :doc:`/tutorials/introductory/pyplot`
79+
- :ref:`Pyplot examples <pyplots_examples>`
80+
81+
.. _api-index:
82+
83+
The pylab API (discouraged)
84+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
85+
86+
.. automodule:: pylab
87+
:no-members:
88+
3389
Modules
3490
-------
3591

@@ -107,54 +163,3 @@ Alphabetical list of modules:
107163
toolkits/axes_grid1.rst
108164
toolkits/axisartist.rst
109165
toolkits/axes_grid.rst
110-
111-
112-
.. _usage_patterns:
113-
114-
Usage patterns
115-
--------------
116-
117-
Below we describe several common approaches to plotting with Matplotlib.
118-
119-
The pyplot API
120-
^^^^^^^^^^^^^^
121-
122-
`matplotlib.pyplot` is a collection of functions that make
123-
Matplotlib work like MATLAB. Each pyplot function makes some change to a
124-
figure: e.g., creates a figure, creates a plotting area in a figure, plots
125-
some lines in a plotting area, decorates the plot with labels, etc.
126-
127-
`.pyplot` is mainly intended for interactive plots and simple cases of
128-
programmatic plot generation.
129-
130-
Further reading:
131-
132-
- The `matplotlib.pyplot` function reference
133-
- :doc:`/tutorials/introductory/pyplot`
134-
- :ref:`Pyplot examples <pyplots_examples>`
135-
136-
.. _api-index:
137-
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 9E88 :
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-
156-
The pylab API (discouraged)
157-
^^^^^^^^^^^^^^^^^^^^^^^^^^^
158-
159-
.. automodule:: pylab
160-
:no-members:

‎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", explicit object-oriented code,
7+
rather than use the implicit pyplot interface to Matplotlib. This example
8+
shows you how to take advantage of the explicit Matplotlib interface.
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 through the implicit pyplot
14+
interface because managing the *current figure* is cumbersome and
15+
error-prone. Instead, we recommend using the explicit approach and call
16+
methods on Figure and Axes instances. See :ref:`api_interfaces` for an
17+
explanation of the trade-offs between the implicit and explicit interfaces.
1718
1819
"""
1920
import matplotlib.pyplot as plt

‎lib/matplotlib/__init__.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,13 @@
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 to this suggestion are the pyplot
23+
functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and
24+
`.pyplot.savefig`, which can greatly simplify scripting. See
25+
:ref:`api_interfaces` for an explanation of the tradeoffs between the implicit
26+
and explicit interfaces.
2427
2528
Modules include:
2629
@@ -79,6 +82,7 @@
7982
8083
Occasionally the internal documentation (python docstrings) will refer
8184
to MATLAB&reg;, a registered trademark of The MathWorks, Inc.
85+
8286
"""
8387

8488
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: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,19 @@
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 trade-offs between the
24+
explicit and implicit 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
29-
</tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
30-
interface.
26+
In the explicit object-oriented (OO) interface we directly utilize instances of
27+
:class:`axes.Axes` to build up the visualization in an instance of
28+
:class:`figure.Figure`. In the implicit interface, inspired by and modeled on
29+
MATLAB, uses an global state-based interface which is is encapsulated in the
30+
:mod:`.pyplot` module to plot to the "current Axes". See the :doc:`pyplot
31+
tutorials </tutorials/introductory/pyplot>` for a more in-depth look at the
32+
pyplot interface.
3133
3234
Most of the terms are straightforward but the main thing to remember
3335
is that:
@@ -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 prefer the explicit interface over the implicit pyplot interface
47+
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-offs between 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 less verbose but also not as flexible as 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