Skip to content

Commit 71ddfe1

Browse files
neil-gurnanineil-gurnani
authored
Merge branch 'matplotlib:main' into mnt-make-cla-an-alias-for-clear
2 parents 20f8c8b + 2aa4b7d commit 71ddfe1

31 files changed

+656
-310
lines changed

‎doc/api/index.rst

+56-51
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:
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/api/next_api_changes/deprecations/22797-OG.rst

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Deprecation of helper functions in backends
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
The following functions are considered private and deprecated. Vendor the code
5+
of the similarly named private functions if you rely on these functions.
6+
7+
* ``backend_pdf.fill``
8+
* ``backend_ps.quote_ps_string``
9+
* ``backend_svg.escape_attrib``
10+
* ``backend_svg.escape_cdata``
11+
* ``backend_svg.escape_comment``
12+
* ``backend_svg.short_float_fmt``

‎doc/users/project/history.rst

+1-1
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

+6-5
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

+5-4
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

+8-4
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/axes/_base.py

+6-6
Original file line numberDiff line numberDiff line change
@@ -169,25 +169,25 @@ def _process_plot_format(fmt):
169169
if fmt[i:i+2] in mlines.lineStyles: # First, the two-char styles.
170170
if linestyle is not None:
171171
raise ValueError(
172-
'Illegal format string "%s"; two linestyle symbols' % fmt)
172+
f'Illegal format string {fmt!r}; two linestyle symbols')
173173
linestyle = fmt[i:i+2]
174174
i += 2
175175
elif c in mlines.lineStyles:
176176
if linestyle is not None:
177177
raise ValueError(
178-
'Illegal format string "%s"; two linestyle symbols' % fmt)
178+
f'Illegal format string {fmt!r}; two linestyle symbols')
179179
linestyle = c
180180
i += 1
181181
elif c in mlines.lineMarkers:
182182
if marker is not None:
183183
raise ValueError(
184-
'Illegal format string "%s"; two marker symbols' % fmt)
184+
f'Illegal format string {fmt!r}; two marker symbols')
185185
marker = c
186186
i += 1
187187
elif c in mcolors.get_named_colors_mapping():
188188
if color is not None:
189189
raise ValueError(
190-
'Illegal format string "%s"; two color symbols' % fmt)
190+
f'Illegal format string {fmt!r}; two color symbols')
191191
color = c
192192
i += 1
193193
elif c == 'C' and i < len(fmt) - 1:
@@ -2084,8 +2084,8 @@ def axis(self, *args, emit=True, **kwargs):
20842084
self.set_ylim([ylim[0], ylim[0] + edge_size],
20852085
emit=emit, auto=False)
20862086
else:
2087-
raise ValueError('Unrecognized string %s to axis; '
2088-
'try on or off' % s)
2087+
raise ValueError(f"Unrecognized string {s!r} to axis; "
2088+
"try 'on' or 'off'")
20892089
else:
20902090
if len(args) == 1:
20912091
limits = args[0]

‎lib/matplotlib/backends/backend_pdf.py

+9-4
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,12 @@
9393
# * draw_quad_mesh
9494

9595

96+
@_api.deprecated("3.6", alternative="Vendor the code")
9697
def fill(strings, linelen=75):
98+
return _fill(strings, linelen=linelen)
99+
100+
101+
def _fill(strings, linelen=75):
97102
"""
98103
Make one string from sequence of strings, with whitespace in between.
99104
@@ -292,15 +297,15 @@ def pdfRepr(obj):
292297
# anything, so the caller must ensure that PDF names are
293298
# represented as Name objects.
294299
elif isinstance(obj, dict):
295-
return fill([
300+
return _fill([
296301
b"<<",
297302
*[Name(k).pdfRepr() + b" " + pdfRepr(v) for k, v in obj.items()],
298303
b">>",
299304
])
300305

301306
# Lists.
302307
elif isinstance(obj, (list, tuple)):
303-
return fill([b"[", *[pdfRepr(val) for val in obj], b"]"])
308+
return _fill([b"[", *[pdfRepr(val) for val in obj], b"]"])
304309

305310
# The null keyword.
306311
elif obj is None:
@@ -312,7 +317,7 @@ def pdfRepr(obj):
312317

313318
# A bounding box
314319
elif isinstance(obj, BboxBase):
315-
return fill([pdfRepr(val) for val in obj.bounds])
320+
return _fill([pdfRepr(val) for val in obj.bounds])
316321

317322
else:
318323
raise TypeError("Don't know a PDF representation for {} objects"
@@ -833,7 +838,7 @@ def write(self, data):
833838
self.currentstream.write(data)
834839

835840
def output(self, *data):
836-
self.write(fill([pdfRepr(x) for x in data]))
841+
self.write(_fill([pdfRepr(x) for x in data]))
837842
self.write(b'\n')
838843

839844
def beginStream(self, id, len, extra=None, png=None):

‎lib/matplotlib/backends/backend_ps.py

+7-1
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,12 @@ def _nums_to_str(*args):
8989
return " ".join(f"{arg:1.3f}".rstrip("0").rstrip(".") for arg in args)
9090

9191

92+
@_api.deprecated("3.6", alternative="Vendor the code")
9293
def quote_ps_string(s):
94+
return _quote_ps_string(s)
95+
96+
97+
def _quote_ps_string(s):
9398
"""
9499
Quote dangerous characters of S for use in a PostScript string constant.
95100
"""
@@ -738,7 +743,7 @@ def draw_gouraud_triangles(self, gc, points, colors, trans):
738743
streamarr['flags'] = 0
739744
streamarr['points'] = (flat_points - points_min) * factor
740745
streamarr['colors'] = flat_colors[:, :3] * 255.0
741-
stream = quote_ps_string(streamarr.tobytes())
746+
stream = _quote_ps_string(streamarr.tobytes())
742747

743748
self._pswriter.write(f"""\
744749
gsave
@@ -778,6 +783,7 @@ def _draw_ps(self, ps, gc, rgbFace, *, fill=True, stroke=True):
778783
self.set_linejoin(gc.get_joinstyle())
779784
self.set_linecap(gc.get_capstyle())
780785
self.set_linedash(*gc.get_dashes())
786+
if mightstroke or hatch:
781787
self.set_color(*gc.get_rgb()[:3])
782788
write('gsave\n')
783789

0 commit comments

Comments
 (0)