Skip to content

Commit a2cad36

Browse files
tacaswellmeeseeksmachine
tacaswell
authored and
meeseeksmachine
committed
Backport PR #22038: DOC: Include alternatives to deprecations in the documentation
1 parent 8fe19dc commit a2cad36

File tree

11 files changed

+43
-28
lines changed

11 files changed

+43
-28
lines changed

‎doc/devel/contributing.rst

+2
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,8 @@ Introducing
316316
All these helpers take a first parameter *since*, which should be set to
317317
the next point release, e.g. "3.x".
318318

319+
You can use standard rst cross references in *alternative*.
320+
319321
Expiring
320322
~~~~~~~~
321323

‎lib/matplotlib/_api/deprecation.py

+4-1
Original file line numberDiff line numberDiff line change
@@ -207,10 +207,13 @@ def wrapper(*args, **kwargs):
207207
old_doc = inspect.cleandoc(old_doc or '').strip('\n')
208208

209209
notes_header = '\nNotes\n-----'
210+
second_arg = ' '.join([t.strip() for t in
211+
(message, f"Use {alternative} instead."
212+
if alternative else "", addendum) if t])
210213
new_doc = (f"[*Deprecated*] {old_doc}\n"
211214
f"{notes_header if notes_header not in old_doc else ''}\n"
212215
f".. deprecated:: {since}\n"
213-
f" {message.strip()}")
216+
f" {second_arg}")
214217

215218
if not old_doc:
216219
# This is to prevent a spurious 'unexpected unindent' warning from

‎lib/matplotlib/axis.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ def _apply_tickdir(self, tickdir):
211211
self._tickdir = tickdir
212212
self._pad = self._base_pad + self.get_tick_padding()
213213

214-
@_api.deprecated("3.5", alternative="axis.set_tick_params")
214+
@_api.deprecated("3.5", alternative="`.Axis.set_tick_params`")
215215
def apply_tickdir(self, tickdir):
216216
self._apply_tickdir(tickdir)
217217
self.stale = True
@@ -822,7 +822,7 @@ def clear(self):
822822
self.set_units(None)
823823
self.stale = True
824824

825-
@_api.deprecated("3.4", alternative="Axis.clear()")
825+
@_api.deprecated("3.4", alternative="`.Axis.clear`")
826826
def cla(self):
827827
"""Clear this axis."""
828828
return self.clear()

‎lib/matplotlib/backend_bases.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -2341,8 +2341,8 @@ def get_default_filetype(cls):
23412341
"""
23422342
return rcParams['savefig.format']
23432343

2344-
@_api.deprecated(
2345-
"3.4", alternative="manager.get_window_title or GUI-specific methods")
2344+
@_api.deprecated("3.4", alternative="`.FigureManagerBase.get_window_title`"
2345+
" or GUI-specific methods")
23462346
def get_window_title(self):
23472347
"""
23482348
Return the title text of the window containing the figure, or None
@@ -2351,8 +2351,8 @@ def get_window_title(self):
23512351
if self.manager is not None:
23522352
return self.manager.get_window_title()
23532353

2354-
@_api.deprecated(
2355-
"3.4", alternative="manager.set_window_title or GUI-specific methods")
2354+
@_api.deprecated("3.4", alternative="`.FigureManagerBase.set_window_title`"
2355+
" or GUI-specific methods")
23562356
def set_window_title(self, title):
23572357
"""
23582358
Set the title text of the window containing the figure. Note that
@@ -3284,7 +3284,7 @@ def save_figure(self, *args):
32843284
"""Save the current figure."""
32853285
raise NotImplementedError
32863286

3287-
@_api.deprecated("3.5", alternative="canvas.set_cursor")
3287+
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
32883288
def set_cursor(self, cursor):
32893289
"""
32903290
Set the current cursor to one of the :class:`Cursors` enums values.

‎lib/matplotlib/backend_tools.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,7 @@ def _set_cursor_cbk(self, event):
277277
self.canvas.set_cursor(self._default_cursor)
278278
self._last_cursor = self._default_cursor
279279

280-
@_api.deprecated("3.5", alternative="figure.canvas.set_cursor")
280+
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
281281
def set_cursor(self, cursor):
282282
"""
283283
Set the cursor.

‎lib/matplotlib/collections.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -2091,7 +2091,8 @@ def get_coordinates(self):
20912091
return self._coordinates
20922092

20932093
@staticmethod
2094-
@_api.deprecated("3.5", alternative="QuadMesh(coordinates).get_paths()")
2094+
@_api.deprecated("3.5", alternative="`QuadMesh(coordinates).get_paths()"
2095+
"<.QuadMesh.get_paths>`")
20952096
def convert_mesh_to_paths(meshWidth, meshHeight, coordinates):
20962097
return QuadMesh._convert_mesh_to_paths(coordinates)
20972098

‎lib/matplotlib/dates.py

+6-5
Original file line numberDiff line numberDiff line change
@@ -1681,12 +1681,12 @@ def set_axis(self, axis):
16811681
self._wrapped_locator.set_axis(axis)
16821682
return super().set_axis(axis)
16831683

1684-
@_api.deprecated("3.5", alternative=".axis.set_view_interval")
1684+
@_api.deprecated("3.5", alternative="`.Axis.set_view_interval`")
16851685
def set_view_interval(self, vmin, vmax):
16861686
self._wrapped_locator.set_view_interval(vmin, vmax)
16871687
return super().set_view_interval(vmin, vmax)
16881688

1689-
@_api.deprecated("3.5", alternative=".axis.set_data_interval")
1689+
@_api.deprecated("3.5", alternative="`.Axis.set_data_interval`")
16901690
def set_data_interval(self, vmin, vmax):
16911691
self._wrapped_locator.set_data_interval(vmin, vmax)
16921692
return super().set_data_interval(vmin, vmax)
@@ -1722,8 +1722,9 @@ def _get_interval(self):
17221722
return self._interval
17231723

17241724

1725-
@_api.deprecated("3.5",
1726-
alternative="mdates.date2num(datetime.utcfromtimestamp(e))")
1725+
@_api.deprecated(
1726+
"3.5",
1727+
alternative="`date2num(datetime.utcfromtimestamp(e))<.date2num>`")
17271728
def epoch2num(e):
17281729
"""
17291730
Convert UNIX time to days since Matplotlib epoch.
@@ -1745,7 +1746,7 @@ def epoch2num(e):
17451746
return (dt + np.asarray(e)) / SEC_PER_DAY
17461747

17471748

1748-
@_api.deprecated("3.5", alternative="mdates.num2date(e).timestamp()")
1749+
@_api.deprecated("3.5", alternative="`num2date(e).timestamp()<.num2date>`")
17491750
def num2epoch(d):
17501751
"""
17511752
Convert days since Matplotlib epoch to UNIX time.

‎lib/matplotlib/mathtext.py

+9-9
Original file line numberDiff line numberDiff line change
@@ -179,15 +179,15 @@ def get_hinting_type(self):
179179
return backend_agg.get_hinting_flag()
180180

181181

182-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
182+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
183183
class MathtextBackendBitmap(MathtextBackendAgg):
184184
def get_results(self, box, used_characters):
185185
ox, oy, width, height, depth, image, characters = \
186186
super().get_results(box, used_characters)
187187
return image, depth
188188

189189

190-
@_api.deprecated("3.4", alternative="MathtextBackendPath")
190+
@_api.deprecated("3.4", alternative="`.MathtextBackendPath`")
191191
class MathtextBackendPs(MathtextBackend):
192192
"""
193193
Store information to write a mathtext rendering to the PostScript backend.
@@ -231,7 +231,7 @@ def get_results(self, box, used_characters):
231231
used_characters)
232232

233233

234-
@_api.deprecated("3.4", alternative="MathtextBackendPath")
234+
@_api.deprecated("3.4", alternative="`.MathtextBackendPath`")
235235
class MathtextBackendPdf(MathtextBackend):
236236
"""Store information to write a mathtext rendering to the PDF backend."""
237237

@@ -263,7 +263,7 @@ def get_results(self, box, used_characters):
263263
used_characters)
264264

265265

266-
@_api.deprecated("3.4", alternative="MathtextBackendPath")
266+
@_api.deprecated("3.4", alternative="`.MathtextBackendPath`")
267267
class MathtextBackendSvg(MathtextBackend):
268268
"""
269269
Store information to write a mathtext rendering to the SVG
@@ -324,7 +324,7 @@ def get_results(self, box, used_characters):
324324
self.rects)
325325

326326

327-
@_api.deprecated("3.4", alternative="MathtextBackendPath")
327+
@_api.deprecated("3.4", alternative="`.MathtextBackendPath`")
328328
class MathtextBackendCairo(MathtextBackend):
329329
"""
330330
Store information to write a mathtext rendering to the Cairo
@@ -457,7 +457,7 @@ def _parse_cached(self, s, dpi, prop, force_standard_ps_fonts):
457457
font_output.set_canvas_size(box.width, box.height, box.depth)
458458
return font_output.get_results(box)
459459

460-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
460+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
461461
def to_mask(self, texstr, dpi=120, fontsize=14):
462462
r"""
463463
Convert a mathtext string to a grayscale array and depth.
@@ -483,7 +483,7 @@ def to_mask(self, texstr, dpi=120, fontsize=14):
483483
ftimage, depth = self.parse(texstr, dpi=dpi, prop=prop)
484484
return np.asarray(ftimage), depth
485485

486-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
486+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
487487
def to_rgba(self, texstr, color='black', dpi=120, fontsize=14):
488488
r"""
489489
Convert a mathtext string to an RGBA array and depth.
@@ -516,7 +516,7 @@ def to_rgba(self, texstr, color='black', dpi=120, fontsize=14):
516516
RGBA[:, :, 3] = x
517517
return RGBA, depth
518518

519-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
519+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
520520
def to_png(self, filename, texstr, color='black', dpi=120, fontsize=14):
521521
r"""
522522
Render a tex expression to a PNG file.
@@ -544,7 +544,7 @@ def to_png(self, filename, texstr, color='black', dpi=120, fontsize=14):
544544
Image.fromarray(rgba).save(filename, format="png")
545545
return depth
546546

547-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
547+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
548548
def get_depth(self, texstr, dpi=120, fontsize=14):
549549
r"""
550550
Get the depth of a mathtext string.

‎lib/matplotlib/spines.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -222,7 +222,7 @@ def clear(self):
222222
if self.axis is not None:
223223
self.axis.clear()
224224

225-
@_api.deprecated("3.4", alternative="Spine.clear()")
225+
@_api.deprecated("3.4", alternative="`.Spine.clear`")
226226
def cla(self):
227227
self.clear()
228228

‎lib/matplotlib/tests/test_api.py

+8
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,11 @@ def func(pre, arg, post=None):
8585
func(1, 2)
8686
with pytest.warns(_api.MatplotlibDeprecationWarning):
8787
func(1, 2, 3)
88+
89+
90+
def test_deprecation_alternative():
91+
alternative = "`.f1`, `f2`, `f3(x) <.f3>` or `f4(x)<f4>`"
92+
@_api.deprecated("1", alternative=alternative)
93+
def f():
94+
pass
95+
assert alternative in f.__doc__

‎lib/matplotlib/ticker.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -187,17 +187,17 @@ def create_dummy_axis(self, **kwargs):
187187
if self.axis is None:
188188
self.axis = _DummyAxis(**kwargs)
189189

190-
@_api.deprecated("3.5", alternative=".axis.set_view_interval")
190+
@_api.deprecated("3.5", alternative="`.Axis.set_view_interval`")
191191
def set_view_interval(self, vmin, vmax):
192192
self.axis.set_view_interval(vmin, vmax)
193193

194-
@_api.deprecated("3.5", alternative=".axis.set_data_interval")
194+
@_api.deprecated("3.5", alternative="`.Axis.set_data_interval`")
195195
def set_data_interval(self, vmin, vmax):
196196
self.axis.set_data_interval(vmin, vmax)
197197

198198
@_api.deprecated(
199199
"3.5",
200-
alternative=".axis.set_view_interval and .axis.set_data_interval")
200+
alternative="`.Axis.set_view_interval` and `.Axis.set_data_interval`")
201201
def set_bounds(self, vmin, vmax):
202202
self.set_view_interval(vmin, vmax)
203203
self.set_data_interval(vmin, vmax)

0 commit comments

Comments
 (0)