Skip to content

Backport PR #22038 on branch v3.5.x (DOC: Include alternatives to deprecations in the documentation) #22578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 1, 2022
Merged

Backport PR #22038 on branch v3.5.x (DOC: Include alternatives to deprecations in the documentation) #22578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,6 +316,8 @@ Introducing
All these helpers take a first parameter *since*, which should be set to
the next point release, e.g. "3.x".

You can use standard rst cross references in *alternative*.

Expiring
~~~~~~~~

Expand Down
5 changes: 4 additions & 1 deletion lib/matplotlib/_api/deprecation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,10 +207,13 @@ def wrapper(*args, **kwargs):
old_doc = inspect.cleandoc(old_doc or '').strip('\n')

notes_header = '\nNotes\n-----'
second_arg = ' '.join([t.strip() for t in
(message, f"Use {alternative} instead."
if alternative else "", addendum) if t])
new_doc = (f"[*Deprecated*] {old_doc}\n"
f"{notes_header if notes_header not in old_doc else ''}\n"
f".. deprecated:: {since}\n"
f" {message.strip()}")
f" {second_arg}")

if not old_doc:
# This is to prevent a spurious 'unexpected unindent' warning from
Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/axis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ def _apply_tickdir(self, tickdir):
self._tickdir = tickdir
self._pad = self._base_pad + self.get_tick_padding()

@_api.deprecated("3.5", alternative="axis.set_tick_params")
@_api.deprecated("3.5", alternative="`.Axis.set_tick_params`")
def apply_tickdir(self, tickdir):
self._apply_tickdir(tickdir)
self.stale = True
Expand Down Expand Up @@ -822,7 +822,7 @@ def clear(self):
self.set_units(None)
self.stale = True

@_api.deprecated("3.4", alternative="Axis.clear()")
@_api.deprecated("3.4", alternative="`.Axis.clear`")
def cla(self):
"""Clear this axis."""
return self.clear()
Expand Down
10 changes: 5 additions & 5 deletions lib/matplotlib/backend_bases.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2341,8 +2341,8 @@ def get_default_filetype(cls):
"""
return rcParams['savefig.format']

@_api.deprecated(
"3.4", alternative="manager.get_window_title or GUI-specific methods")
@_api.deprecated("3.4", alternative="`.FigureManagerBase.get_window_title`"
" or GUI-specific methods")
def get_window_title(self):
"""
Return the title text of the window containing the figure, or None
Expand All @@ -2351,8 +2351,8 @@ def get_window_title(self):
if self.manager is not None:
return self.manager.get_window_title()

@_api.deprecated(
"3.4", alternative="manager.set_window_title or GUI-specific methods")
@_api.deprecated("3.4", alternative="`.FigureManagerBase.set_window_title`"
" or GUI-specific methods")
def set_window_title(self, title):
"""
Set the title text of the window containing the figure. Note that
Expand Down Expand Up @@ -3284,7 +3284,7 @@ def save_figure(self, *args):
"""Save the current figure."""
raise NotImplementedError

@_api.deprecated("3.5", alternative="canvas.set_cursor")
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
def set_cursor(self, cursor):
"""
Set the current cursor to one of the :class:`Cursors` enums values.
Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/backend_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ def _set_cursor_cbk(self, event):
self.canvas.set_cursor(self._default_cursor)
self._last_cursor = self._default_cursor

@_api.deprecated("3.5", alternative="figure.canvas.set_cursor")
@_api.deprecated("3.5", alternative="`.FigureCanvasBase.set_cursor`")
def set_cursor(self, cursor):
"""
Set the cursor.
Expand Down
3 changes: 2 additions & 1 deletion lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2091,7 +2091,8 @@ def get_coordinates(self):
return self._coordinates

@staticmethod
@_api.deprecated("3.5", alternative="QuadMesh(coordinates).get_paths()")
@_api.deprecated("3.5", alternative="`QuadMesh(coordinates).get_paths()"
"<.QuadMesh.get_paths>`")
def convert_mesh_to_paths(meshWidth, meshHeight, coordinates):
return QuadMesh._convert_mesh_to_paths(coordinates)

Expand Down
11 changes: 6 additions & 5 deletions lib/matplotlib/dates.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1681,12 +1681,12 @@ def set_axis(self, axis):
self._wrapped_locator.set_axis(axis)
return super().set_axis(axis)

@_api.deprecated("3.5", alternative=".axis.set_view_interval")
@_api.deprecated("3.5", alternative="`.Axis.set_view_interval`")
def set_view_interval(self, vmin, vmax):
self._wrapped_locator.set_view_interval(vmin, vmax)
return super().set_view_interval(vmin, vmax)

@_api.deprecated("3.5", alternative=".axis.set_data_interval")
@_api.deprecated("3.5", alternative="`.Axis.set_data_interval`")
def set_data_interval(self, vmin, vmax):
self._wrapped_locator.set_data_interval(vmin, vmax)
return super().set_data_interval(vmin, vmax)
Expand Down Expand Up @@ -1722,8 +1722,9 @@ def _get_interval(self):
return self._interval


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


@_api.deprecated("3.5", alternative="mdates.num2date(e).timestamp()")
@_api.deprecated("3.5", alternative="`num2date(e).timestamp()<.num2date>`")
def num2epoch(d):
"""
Convert days since Matplotlib epoch to UNIX time.
Expand Down
18 changes: 9 additions & 9 deletions lib/matplotlib/mathtext.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,15 +179,15 @@ def get_hinting_type(self):
return backend_agg.get_hinting_flag()


@_api.deprecated("3.4", alternative="mathtext.math_to_image")
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
class MathtextBackendBitmap(MathtextBackendAgg):
def get_results(self, box, used_characters):
ox, oy, width, height, depth, image, characters = \
super().get_results(box, used_characters)
return image, depth


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


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

Expand Down Expand Up @@ -263,7 +263,7 @@ def get_results(self, box, used_characters):
used_characters)


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


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

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

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

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

@_api.deprecated("3.4", alternative="mathtext.math_to_image")
@_api.deprecated("3.4", alternative="`.mathtext.math_to_image`")
def get_depth(self, texstr, dpi=120, fontsize=14):
r"""
Get the depth of a mathtext string.
Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/spines.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ def clear(self):
if self.axis is not None:
self.axis.clear()

@_api.deprecated("3.4", alternative="Spine.clear()")
@_api.deprecated("3.4", alternative="`.Spine.clear`")
def cla(self):
self.clear()

Expand Down
8 changes: 8 additions & 0 deletions lib/matplotlib/tests/test_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,3 +85,11 @@ def func(pre, arg, post=None):
func(1, 2)
with pytest.warns(_api.MatplotlibDeprecationWarning):
func(1, 2, 3)


def test_deprecation_alternative():
alternative = "`.f1`, `f2`, `f3(x) <.f3>` or `f4(x)<f4>`"
@_api.deprecated("1", alternative=alternative)
def f():
pass
assert alternative in f.__doc__
6 changes: 3 additions & 3 deletions lib/matplotlib/ticker.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,17 +187,17 @@ def create_dummy_axis(self, **kwargs):
if self.axis is None:
self.axis = _DummyAxis(**kwargs)

@_api.deprecated("3.5", alternative=".axis.set_view_interval")
@_api.deprecated("3.5", alternative="`.Axis.set_view_interval`")
def set_view_interval(self, vmin, vmax):
self.axis.set_view_interval(vmin, vmax)

@_api.deprecated("3.5", alternative=".axis.set_data_interval")
@_api.deprecated("3.5", alternative="`.Axis.set_data_interval`")
def set_data_interval(self, vmin, vmax):
self.axis.set_data_interval(vmin, vmax)

@_api.deprecated(
"3.5",
alternative=".axis.set_view_interval and .axis.set_data_interval")
alternative="`.Axis.set_view_interval` and `.Axis.set_data_interval`")
def set_bounds(self, vmin, vmax):
self.set_view_interval(vmin, vmax)
self.set_data_interval(vmin, vmax)
Expand Down