Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1675a04

Browse files
tacaswelltacaswell
authored
Merge pull request #22038 from StefRe/enh/doc_deprecation
DOC: Include alternatives to deprecations in the documentation
2 parents 45de25e + baa99d3 commit 1675a04

File tree

11 files changed

+43
-28
lines changed

11 files changed

+43
-28
lines changed

‎doc/devel/contributing.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,8 @@ Introducing
326326
All these helpers take a first parameter *since*, which should be set to
327327
the next point release, e.g. "3.x".
328328

329+
You can use standard rst cross references in *alternative*.
330+
329331
Expiring
330332
~~~~~~~~
331333

‎lib/matplotlib/_api/deprecation.py

Lines changed: 4 additions & 1 deletion
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2285,8 +2285,8 @@ def get_default_filetype(cls):
22852285
"""
22862286
return rcParams['savefig.format']
22872287

2288-
@_api.deprecated(
2289-
"3.4", alternative="manager.get_window_title or GUI-specific methods")
2288+
@_api.deprecated("3.4", alternative="`.FigureManagerBase.get_window_title`"
2289+
" or GUI-specific methods")
22902290
def get_window_title(self):
22912291
"""
22922292
Return the title text of the window containing the figure, or None
@@ -2295,8 +2295,8 @@ def get_window_title(self):
22952295
if self.manager is not None:
22962296
return self.manager.get_window_title()
22972297

2298-
@_api.deprecated(
2299-
"3.4", alternative="manager.set_window_title or GUI-specific methods")
2298+
@_api.deprecated("3.4", alternative="`.FigureManagerBase.set_window_title`"
2299+
" or GUI-specific methods")
23002300
def set_window_title(self, title):
23012301
"""
23022302
Set the title text of the window containing the figure. Note that
@@ -3228,7 +3228,7 @@ def save_figure(self, *args):
32283228
"""Save the current figure."""
32293229
raise NotImplementedError
32303230

3231-
@_api.deprecated("3.5", alternative="canvas.set_cursor")
3231+
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
32323232
def set_cursor(self, cursor):
32333233
"""
32343234
Set the current cursor to one of the :class:`Cursors` enums values.

‎lib/matplotlib/backend_tools.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ def _set_cursor_cbk(self, event):
309309
self.canvas.set_cursor(self._default_cursor)
310310
self._last_cursor = self._default_cursor
311311

312-
@_api.deprecated("3.5", alternative="figure.canvas.set_cursor")
312+
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
313313
def set_cursor(self, cursor):
314314
"""
315315
Set the cursor.

‎lib/matplotlib/collections.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2076,7 +2076,8 @@ def get_coordinates(self):
20762076
return self._coordinates
20772077

20782078
@staticmethod
2079-
@_api.deprecated("3.5", alternative="QuadMesh(coordinates).get_paths()")
2079+
@_api.deprecated("3.5", alternative="`QuadMesh(coordinates).get_paths()"
2080+
"<.QuadMesh.get_paths>`")
20802081
def convert_mesh_to_paths(meshWidth, meshHeight, coordinates):
20812082
return QuadMesh._convert_mesh_to_paths(coordinates)
20822083

‎lib/matplotlib/dates.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1685,12 +1685,12 @@ def set_axis(self, axis):
16851685
self._wrapped_locator.set_axis(axis)
16861686
return super().set_axis(axis)
16871687

1688-
@_api.deprecated("3.5", alternative=".axis.set_view_interval")
1688+
@_api.deprecated("3.5", alternative="`.Axis.set_view_interval`")
16891689
def set_view_interval(self, vmin, vmax):
16901690
self._wrapped_locator.set_view_interval(vmin, vmax)
16911691
return super().set_view_interval(vmin, vmax)
16921692

1693-
@_api.deprecated("3.5", alternative=".axis.set_data_interval")
1693+
@_api.deprecated("3.5", alternative="`.Axis.set_data_interval`")
16941694
def set_data_interval(self, vmin, vmax):
16951695
self._wrapped_locator.set_data_interval(vmin, vmax)
16961696
return super().set_data_interval(vmin, vmax)
@@ -1726,8 +1726,9 @@ def _get_interval(self):
17261726
return self._interval
17271727

17281728

1729-
@_api.deprecated("3.5",
1730-
alternative="mdates.date2num(datetime.utcfromtimestamp(e))")
1729+
@_api.deprecated(
1730+
"3.5",
1731+
alternative="`date2num(datetime.utcfromtimestamp(e))<.date2num>`")
17311732
def epoch2num(e):
17321733
"""
17331734
Convert UNIX time to days since Matplotlib epoch.
@@ -1749,7 +1750,7 @@ def epoch2num(e):
17491750
return (dt + np.asarray(e)) / SEC_PER_DAY
17501751

17511752

1752-
@_api.deprecated("3.5", alternative="mdates.num2date(e).timestamp()")
1753+
@_api.deprecated("3.5", alternative="`num2date(e).timestamp()<.num2date>`")
17531754
def num2epoch(d):
17541755
"""
17551756
Convert days since Matplotlib epoch to UNIX time.

‎lib/matplotlib/mathtext.py

Lines changed: 9 additions & 9 deletions
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.
@@ -512,7 +512,7 @@ def to_rgba(self, texstr, color='black', dpi=120, fontsize=14):
512512
rgba[:, :, 3] = alpha
513513
return rgba, depth
514514

515-
@_api.deprecated("3.4", alternative="mathtext.math_to_image")
515+
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
516516
def to_png(self, filename, texstr, color='black', dpi=120, fontsize=14):
517517
r"""
518518
Render a tex expression to a PNG file.
@@ -540,7 +540,7 @@ def to_png(self, filename, texstr, color='black', dpi=120, fontsize=14):
540540
Image.fromarray(rgba).save(filename, format="png")
541541
return depth
542542

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

‎lib/matplotlib/spines.py

Lines changed: 1 addition & 1 deletion
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

Lines changed: 8 additions & 0 deletions
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

Lines changed: 3 additions & 3 deletions
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)